Suggestions for documenting namespaces with Doxygen

Question

Consider several C++ classes which are all defined in a particular namespace. For cleanliness, each class is located within its own file, and are each well-documented.

For the purposes of completing the documentation with Doxygen, we'd also like to add documentation for the namespace itself.

Does anyone have any suggestions for a good best-practice solution for this? We've got a couple of options:

• A dedicated namespace.h file which contains only the namespace and the documentation for it. This means there is a single location to describe the namespace, but does mean having a seemingly purposeless file.
• Add the description for the namespace inside one of the class files (such as the most significant one?). This means not having to add a new file, but does make it harder to find the description if there ever is a need to modify it.

• BobDalgleish: The documentation file is not "purposeless" - it is for documentation.
• John Go-Soco: @BobDalgleish True. I meant "purposeless" purely in terms of code compilation and not for anyone reading it. Its presence, though beneficial in terms of documentation, does also contribute to the number of relevant header files and therefore to the "noise" which the developer needs to get their head around.

Answer 1

Generally speaking, for most libraries, you'll have a single header that includes all of the other files of interest in your library. Or at least, the majority of them.

That's a good place to document the namespace, even if that file never directly uses it. Just create an empty namespace Name {} declaration.

Answer 2

The convention here is to create a documentation-only file. By default, Doxygen uses file extension .dox to provide a place for your documentation which. The extension allows you to differentiate the documentation files from a header file that contains some code influencing your program.

Note that the .dox files (unlike .rst or .md files) are still treated like any other source files. You must mark your documentation as a comment!

Use \namespace (or @namespace, if you are Javadoc friend) to specify which namespace you are documenting:

/** \namespace my::name::space::name \brief
 *
 * Lorem ipsum dolor sit amet.
 *
 * Extended documentation for your namespace.
 *
 * \par Named paragraph
 * Lorem ipsum.
 */

If your namespace lies entirely in one file, or when you can consider some namespace to be the "main" file of the namespace, it can be better to include the namespace documentation in you code:

/** \brief
 * This is a documentation comment!
 */
namespace foo
{
// ...
}

If you want to provide more extensive documentation for a part of your project, you are probably looking for either the \page command or creating standalone .md, .rst or .dox files. If you create .md or .rst file, the Doxygen (in the default configuration) simply embeds that file in a separate part of your documentation. In stand-alone documentation (created as a .md/.rst file or using \page), you can use sectioning commands. For \page, these are, for example, \section or \subsection. Note that these commands are not allowed in ordinary documentation comments.

For every your project, consider polishing out your documentation by adding file containing the \mainpage command to provide a main page for the documentation.