Thomas Matthews Thomas Matthews - 14 days ago 8
C++ Question

Documenting namespaces with Doxygen

I'm having issues with Doxygen recognizing namespaces and modules. I believe the issue surrounds whether to place the

\addtogroup
within the namespace or outside the namespace.

Example 1, outside the namespace:



/*!
* \addtogroup Records
* @{
*/

//! Generic record interfaces and implementations
namespace Records
{

//! Describes the record interface
class Interface;

} // End namespace Records

/*! @} End of Doxygen Groups*/


Example 2 - within namespace



//! Generic record interfaces and implementations
namespace Records
{
/*!
* \addtogroup Records
* @{
*/


//! Describes the record interface
class Interface;

/*! @} End of Doxygen Groups*/

} // End namespace Records


I would like the
namespace Records
to appear under the Doxygen Namespaces tab and indirectly under the Modules tab. Clicking on the item in the Namespaces page should produce a page containing
Records::Interface
. Clicking on the item in the Modules tab should also produce a page containing
Records::Interface
.

In my Doxygen documentation, I have items missing from Namespaces tab that are in Modules and vice-versa, due to my inconsistency resulting from this dilemma.

So which is the proper method, Example 1 or Example 2?
{The Doxygen manual is not clear on this topic.}

Doxygen: \addtogroup

Doxygen: documenting namespaces

Answer

I have performed an experiment using Doxygen and the two examples and here are the results. The class names in the examples have been renamed to avoid confusion with Doxygen.

Example 1, Outside Namespace

/*!
 *  \addtogroup Records
 *  @{
 */

//! Generic record interfaces and implementations
namespace Records
{

  //! Describes the record interface  
  class Interface;

} // End namespace Records

/*! @} End of Doxygen Groups*/

Doxygen Results:

Click on Modules button (in the main bar).
Click on "Records" module in the window.

Records & Namespaces screen snapshot

Example 2: Within Namespace (class renamed to Fields)

//! Generic record interfaces and implementations
namespace Fields
{
/*!
 *  \addtogroup Fields
 *  @{
 */


  //! Describes the record interface  
  class Interface;

/*! @} End of Doxygen Groups*/

} // End namespace Fields

Doxygen Results:

Click on Modules button (in the main bar).
Click on "Records" module in the window.

Records & Namespaces screen snapshot within namespace

Summary

The location of Doxygen \addtogroup command has different results depending on whether it is located within a namespace definition or outside. When declared outside of a namespace, the Doxygen Modules tab will show the namespace, as shown in Example 1 above. When the \addtogroup command is placed inside a namespace, the Doxygen Modules tab will not display the namespaces as shown in Example 2 above. If you want your namespace to be listed in the Doxygen Modules tab, locate the \addtogroup command outside of the namespace.