使用 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 Namespaces 选项卡下，并间接显示在 Modules 选项卡下。单击 Namespaces 页面中的项目应生成包含Records::Interface 的页面。单击 Modules 选项卡中的项目也会生成一个包含Records::Interface 的页面。

在我的 Doxygen 文档中，我在 Modules 中的 Namespaces 选项卡中缺少一些项目，反之亦然，这是由于这种困境导致我的不一致。

那么哪个是正确的方法，示例 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

您也可以在命名空间文档中使用\ingroupRecords：

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