使用Doxygen记录命名空间

Question

我遇到了Doxygen识别命名空间和模块的问题。我认为问题围绕着是否将\addtogroup置于命名空间内或命名空间之外。

示例1，在命名空间之外：

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

//! Generic record interfaces and implementations
namespace Records
{

  //! Describes the record interface  
  class Interface;

} // End namespace Records

/*! @} End of Doxygen Groups*/

示例2 - 在命名空间

中

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


  //! Describes the record interface  
  class Interface;

/*! @} End of Doxygen Groups*/

} // End namespace Records

我希望namespace Records显示在Doxygen 命名空间标签下，并间接显示在模块标签下。单击命名空间页面中的项目应生成包含Records::Interface的页面。单击 Modules 选项卡中的项目也应生成包含Records::Interface的页面。

在我的Doxygen文档中，模块中的命名空间标签中缺少项目，反之亦然，原因是由于这种困境导致我的不一致。

那么适当的方法，例1还是例2？ {Doxygen手册对此主题不清楚。}
Doxygen: \addtogroup
Doxygen: documenting namespaces

Answer 1

我使用Doxygen和两个例子进行了实验，结果如下。 示例中的类名已重命名，以避免与Doxygen混淆。

示例1，外部命名空间

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

//! Generic record interfaces and implementations
namespace Records
{

  //! Describes the record interface  
  class Interface;

} // End namespace Records

/*! @} End of Doxygen Groups*/

Doxygen结果：

单击“模块”按钮（在主栏中） 单击窗口中的“记录”模块。

示例2：在命名空间内（重命名为字段的类）

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


  //! Describes the record interface  
  class Interface;

/*! @} End of Doxygen Groups*/

} // End namespace Fields

Doxygen结果：

单击“模块”按钮（在主栏中） 单击窗口中的“记录”模块。

摘要

Doxygen \addtogroup命令的位置具有不同的结果，具体取决于它是位于namespace定义内还是位于外部。在命名空间外声明时，Doxygen Modules 选项卡将显示命名空间，如上面的示例1所示。当\addtogroup命令放在命名空间内时，Doxygen Modules 选项卡将不显示命名空间，如上面的示例2所示。 如果您希望在Doxygen Modules 选项卡中列出您的命名空间，请在命名空间之外找到\addtogroup命令。

Answer 2

作为替代方案，您还可以在命名空间文档中使用\ingroup Records：

/**
 * \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 */