CODEWITHSUNDEEP
doxygen
timos
timos

Reputation: 2707

Separate "internal" from "external" documentation in doxygen

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?

Upvotes: 17

Views: 9725

Answers (3)

Fabian
Fabian

Reputation: 4211

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).

Upvotes: 2

Thomas O'Dell
Thomas O'Dell

Reputation: 554

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

Upvotes: 14

Mike Kwan
Mike Kwan

Reputation: 24477

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.).

Upvotes: 21

Related Questions