如何为使用 Doxygen 的类提供示例代码？答案

【问题标题】：How do I give example code for a class with Doxygen?如何为使用 Doxygen 的类提供示例代码？
【发布时间】：2012-07-28 12:41:24
【问题描述】：

我正在尝试记录嵌入在命名空间中的类，并且我想给出示例用法。我已经编写并包含了示例，它们显示在示例选项卡中。但是，它们没有在类本身中引用。比如this page上的代码，他们的Doxygen命令写成：

/** \example example_test.cpp
 * This is an example of how to use the Test class.
 * More details about this example.
 */

Doxygen 似乎解析了命令和文件，并识别出引用了 Test 类。这对我来说似乎没有发生。此功能没有很好的文档记录，Google 几乎不可能。

这是我的代码的总体布局：

namespace exampleSpace
{
  ///Doxygen documentation

  class exampleClass {};

  ///@example example1.cpp
  ///  example1 description
  ///@example example2.cpp
  ///  example2 description
}

示例描述为类命名，官方文档中的描述也是如此。然而，Doxygen 似乎认出了他们的而不是我的。

我的示例代码是完整的并且可以正确编译/运行。

那么放置这些命令的正确位置在哪里，以便 Doxygen 知道它们是这个特定类的示例？

编辑：似乎 Doxygen 实际上正在解析源代码，因为它成功链接到代码中的类和任何成员函数。但是，课程页面本身并没有链接到文件。

【问题讨论】：

它可能希望您也有文件和类描述。我不记得这对我有什么帮助。
我不完全确定你的意思。你是说@example 命令需要一个类描述吗？从文档来看，似乎并非如此。我什至不知道如何指定它。
您是否在 Doxygen 配置文件中正确设置了EXAMPLE_PATH？
是的。正在显示和解析文件。事实上，似乎显式声明第一个类对象的命名空间使其工作。

标签： c++ class doxygen

【解决方案1】：

我为此使用了\snippet。您引用另一个文件，在该文件中，您可以用[mytag] 区域包围代码块。然后在使用\snippet 的位置显示这些内容。

另请参阅https://stackoverflow.com/a/35759133/356726 和 https://stackoverflow.com/a/16034375/356726

【讨论】：

【解决方案2】：

目前只是一个猜测，但我敢打赌 Doxygen 不会因为命名空间而匹配。

实现链接的一些想法：

明确限定示例中所有名称的命名空间
将代码放在命名空间中的示例中

【讨论】：

这就是我的怀疑，但我想如果代码编译并运行它会起作用。有什么可以尝试调试的吗？我几乎处于停滞状态。编辑：看起来它正在解析，因为类和方法链接到它们各自的 Doxygen 页面。
嗯，显式使用命名空间（即exampleSpace::exampleClass）而不是using namespace exampleSpace; 似乎可以解决问题。
@Littlegator 是的，如果您考虑一下，当存在不合格的名称时，除非您解析所有包含的文件，否则无法知道它来自哪个命名空间。我不知道 doxygen 是否支持using exampleSpace::exampleClass 以减少打字并仍然建立链接