如果在同一级别，Doxygen（或其他工具）文档类和命名空间类似

Question

我有一堆命名空间（包含自由函数）和类（显然包含成员函数），每个都在顶层有一个Doxygen注释，并为其成员提供一些Doxygen注释。它们位于顶级命名空间（整个项目中的一个）和辅助命名空间（将项目分解为包）。像这样：

• proj/pkg1/foo.hpp：class proj::pkg1::Foo
• proj/pkg1/bar.hpp：class proj::pkg1::Bar
• proj/pkg1/baz.hpp：namespace proj::pkg1::Baz
• proj/pkg2/one.hpp：class proj::pkg2::One
• proj/pkg2/two.hpp：namespace proj::pkg2::Two

我没有任何@file评论。它们完全是冗余的，因为每个组件已经有一个主要注释，它附加​​到主类或命名空间。

我尝试通过Doxygen运行它，结果是一团糟：

• 命名空间和类在标题行和导航面板中分为两个不同的层次结构。但我希望它们都在一棵树上，因为例如pkg2::One属于pkg2::Two。
• 名称空间的主要层次结构隐藏在导航面板下的三个级别（项目名称 - >名称空间 - >名称空间列表）。它位于“命名空间成员”旁边 - 谁使用它！？
• 文件（和目录）还有另一个层次结构。这是多余的，因为它们完全匹配命名空间（和类）的层次结构。
• 现在这有点偏僻，但我也想在包名称空间中添加注释。它们具有分离类和命名空间的相同问题（不是那么重要），但也显示各种自由函数，例如operator<<(proj::pkg2::One。

有什么方法可以清理一下吗？也许与狮身人面像和呼吸？

屏幕截图示例

以下是Doxygen在上面的代码中默认生成的内容（它甚至没有提到Baz和Two！），以及我更喜欢它的样子：

Answer 1

这是一个特别可怕的黑客，但我提到它的记录。您可以决定Doxygen最好地处理类，并将所有组件名称空间（第三级名称空间）重新标记为类。像这样：

namespace proj {
namespace pkg1 {

/// @brief The Doxygen comment goes here.
#ifdef DOXYGEN
class
#else
namespace
#endif
Baz {

然后在PREDEFINED = DOXYGEN中设置Doxyfile。

显然，这样做的缺点是它在源代码中看起来很丑陋，而且它在文档中显示为“类”令人困惑。

Answer 2

为了让球滚动，这是一个可能的解决方案：

稍微改变期望：不要希望一次性向读者呈现两级结构，而是一次性提出部分结构。让用户单击树中每个命名空间的单独页面：

• proj命名空间的文档页面显示了它包含的所有包（即在示例中它显示了命名空间pkg1和pkg2）。
• 每个包命名空间页面都显示其中的所有类和组件命名空间（在单独的列表中，这有点令人讨厌，但至少每个包的所有内容都在一起）。

您可以使用GENERATE_TREEVIEW=NO隐藏树视图并隐藏标题行DISABLE_INDEX=YES。

主页可以只是到顶级proj命名空间页面的链接（主页的常用内容移动到proj详细说明），代码如下：

/**
@mainpage
@ref proj "Click here for the proj documentation"
*/

稍有不同的是使用这样的代码手动列出主页面中的包，并绕过proj命名空间页面。这适用于没有整体顶级命名空间的项目，或者您希望更好地控制主页面的项目。

/**
@mainpage

Packages:
- @ref proj::pkg1 @n @copybrief proj::pkg1
- @ref proj::pkg2 @n @copybrief proj::pkg2
*/