记录跨多个文件的命名空间 doxygen

Question

考虑我有2个头文件。

// HEADER 1
/**
 * Doc  for Foo here?
 */
namespace Foo {
  class This {...};
}

&&

// HEADER 2
/**
 * Doc for Foo here?
 */
namespace Foo {
  class That {...};
}

使用Doxygen进行文档编写时，应该如何处理这个问题？

- rhubarb

Answer 1

也许两者都不是最好的选择。

举个例子，假设你有一个名为"<root>/utility/header1.hpp"的文件，它内容在namespace utility中。还有一个名为"<root>/utility/header2.hpp"的文件，内容也在其中。

你可以添加一个文件："<root>/utility.hpp"，记录了utility命名空间。你可以在顶部加上#error Documentation only.来确保它不会被意外地包含进来。

但我建议至少将其放在一个合理的位置（而不是与某些类随意混合在一起）。

- GManNickG

---

你不需要为每个命名空间都准备一个特殊的文件。你可以使用一个全局的“项目文档”文件来提供项目的前端文档、设置组（用于/ingroup标记）并在一个地方记录所有命名空间的文档。这样，所有的“概述”都能被保存在一个逻辑位置，而不是散乱到各处。你甚至可以将这个核心文档放在一个“文档”文件夹中，该文件夹还包含像Doxygen配置文件等其他内容。 - Jason Williams

@Jason 在阅读了这个答案之后，我也是倾向于这个方案。听起来不错。 - rhubarb

@JasonWilliams：我认为你的建议值得一篇独立的回答。我相信这是更好的方法。 - NobodysNightmare

Answer 2

我已将跨多个文件的命名空间文档放入另一个文件中。我的Doxygen构建使用一个单独的文件来处理@mainpage标签。这形成了Doxygen的根，也是这些命名空间的中心位置。

所以我会有一个project_name_mainpage.h文件，在该文件中：

/**
@mainpage title
...whatever you want to tell the user about your application...
*/

/**
 * @namespace your_namespace
 * @brief An awesome description
 * @details More sweet details
 */

将所有内容保存在一个位置，若需要更新，相对容易找到。

- Nate Anderson

Answer 3

找到最适合放置文档的位置，无论是在这些文件中还是完全另外一个地方。使用带有Doxygen命名空间标记的注释块：

/**
 * @namespace Foo
 * Documentation for Foo here. More docs for Foo here,
 * and down here.
 */

文档在这里：http://www.doxygen.nl/manual/commands.html#cmdnamespace

- ssube