Documenting namespaces with Doxygen
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.
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.
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.
As an alternative, you could also use \ingroup
Records
in the namespace documentation:
/**
* \defgroup Records Title for records module
* @brief Short doc of Records
*
* Long doc of Records.
*/
/**
* @brief Generic record interfaces and implementations
*
* \ingroup Records
*/
namespace Records {
/// Describes the record interface
class Interface;
} /* namespace Records */