C++ 使用 Doxygen 记录命名空间
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/2275601/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
Documenting namespaces with Doxygen
提问by Thomas Matthews
I'm having issues with Doxygen recognizing namespaces and modules. I believe the issue surrounds whether to place the \addtogroupwithin the namespace or outside the namespace.
我在 Doxygen 识别命名空间和模块时遇到问题。我认为问题在于是将\addtogroup放在命名空间内还是命名空间外。
Example 1, outside the namespace:
示例 1，命名空间之外：
/*!
* \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
示例 2 - 在命名空间内
//! 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 Recordsto appear under the Doxygen Namespacestab and indirectly under the Modulestab. Clicking on the item in the Namespacespage should produce a page containing Records::Interface. Clicking on the item in the Modulestab should also produce a page containing Records::Interface.
我希望namespace Records出现在 Doxygen命名空间选项卡下，并间接出现在模块选项卡下。单击Namespaces页面中的项目应该会生成一个包含Records::Interface. 单击“模块”选项卡中的项目还应生成一个包含Records::Interface.
In my Doxygen documentation, I have items missing from Namespacestab that are in Modulesand vice-versa, due to my inconsistency resulting from this dilemma.
在我的 Doxygen 文档中，我的命名空间选项卡中缺少模块中的项目，反之亦然，这是由于这种困境导致我的不一致。
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
那么哪个是正确的方法，示例 1 还是示例 2？{Doxygen 手册对此主题不清楚。}
Doxygen：\addtogroup
Doxygen：记录命名空间
回答by Thomas Matthews
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.
我使用 Doxygen 和两个例子进行了一个实验，这是结果。示例中的类名已重命名以避免与 Doxygen 混淆。
Example 1, Outside Namespace
示例 1，外部命名空间
/*!
* \addtogroup Records
* @{
*/
//! Generic record interfaces and implementations
namespace Records
{
//! Describes the record interface
class Interface;
} // End namespace Records
/*! @} End of Doxygen Groups*/
Doxygen Results:
Doxygen 结果：
Click on Modules button (in the main bar).
Click on "Records" module in the window.
单击模块按钮（在主栏中）。
单击窗口中的“记录”模块。
Example 2: Within Namespace (class renamed to Fields)
示例 2：在命名空间内（类重命名为 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:
Doxygen 结果：
Click on Modules button (in the main bar).
Click on "Records" module in the window.
单击模块按钮（在主栏中）。
单击窗口中的“记录”模块。
Summary
概括
The location of Doxygen \addtogroupcommand has different results depending on whether it is located within a namespacedefinition or outside. When declared outside of a namespace, the Doxygen Modulestab will show the namespace, as shown in Example 1 above. When the \addtogroupcommand is placed inside a namespace, the Doxygen Modulestab will not display the namespaces as shown in Example 2 above. If you want your namespace to be listed in the Doxygen Modulestab, locate the \addtogroupcommand outside of the namespace.
Doxygen\addtogroup命令的位置根据是在namespace定义内还是在定义外，会有不同的结果。在命名空间之外声明时，Doxygen模块选项卡将显示命名空间，如上面的示例 1 所示。当\addtogroup命令放置在命名空间内时，Doxygen模块选项卡将不会显示命名空间，如上面的示例 2 所示。 如果您希望在 Doxygen模块选项卡中列出您的命名空间\addtogroup，请在命名空间之外找到该命令。
回答by John
As an alternative, you could also use \ingroupRecordsin the namespace documentation:
作为替代方案，您还可以在命名空间文档中使用：\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 */
