I want to document a library with doxygen. The documentation will be read by two classes of people: Users, which are only interested in the external API and developers which want to see documentation for all functions/structures.
I would like to use to separate doxyfiles to create the documentation. Is there some "tag" I can put in a comment block to mark a comment as internal/external?
Set INTERNAL_DOCS:
# The INTERNAL_DOCS tag determines if documentation
# that is typed after a \internal command is included. If the tag is set
# to NO (the default) then the documentation will be excluded.
# Set it to YES to include the internal documentation.
INTERNAL_DOCS = NO
In the documentation, you can use \internal or @internal at whatever granularity you want (file, function, etc.).
Use the \cond command:
\internal (@internal) only has granularity for the current comment block. It does not allow you any way to hide a structure definition in C.
The easiest way to do this is put
\cond INTERNAL
at the top of an internal header file and
\endcond
at the bottom. Then, in your configuration file, you add
ENABLED_SECTIONS = INTERNAL
to allow the internal items to be included in the documentation.
This way is also recommended by Doxygen users, e.g. here
This is a simple solution which makes use of the fact that you can usually distinguish the internal and external parts of your code into files.
You can simply limit the input files to only those header files which you want to expose in the external documentation:
# For internal, we parse all files
INPUT = ./
# For external, we parse only the files containing the public interface
INPUT = include/header1.hpp include/header2.hpp
This has the advantage that the source files do not have to be modified (with \internal or @internal).
publicvsinternalfunction modifiers.. – Blorgbeard