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

时间：2019-02-27 22:16:20

标签： doxygen python-sphinx

我有一堆命名空间（包含自由函数）和类（显然包含成员函数），每个命名空间在顶层都有一个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！），我希望它看起来像这样：

Example mock screen shot

2 个答案:

答案 0 :(得分：1)

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

namespace proj {
namespace pkg1 {

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

然后在PREDEFINED = DOXYGEN中设置Doxyfile。

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

答案 1 :(得分：0)

要使球滚动起来，这是一个可能的解决方案：

稍微改变一下期望：与其一味地希望一次呈现给读者两个层次的结构，不如一次提出一部分。使用户单击树中每个命名空间的单独页面：

  • 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
*/
相关问题
最新问题