如何将示例与 Doxygen 集成？ [关闭]答案

【问题标题】：How to integrate examples with Doxygen? [closed]如何将示例与 Doxygen 集成？ [关闭]
【发布时间】：2012-02-17 14:14:36
【问题描述】：

我记录了我的所有类，现在我想集成一个如何使用这些类的示例。我怎么做？

【问题讨论】：

标签： documentation doxygen

【解决方案1】：

您可以将示例源代码放在EXAMPLE_PATH 下doxygen 配置中定义的特殊路径中，然后插入带有@example 标签的示例。

Doxygen 然后会生成一个包含示例源代码的额外页面。它还将从包含示例标记的类文档中设置一个指向它的链接。

或者，如果您想使用小代码 sn-ps，您可以使用 @code ... @endcode 插入它们

这方面的文档在这里： doxygen documentation?

【讨论】：

是的，我这样做了，但是额外页面中的 .cpp 文件是空的：/
hmmm doxygen 是否给出任何警告或错误？
没有。我将示例文件包含在 INPUT 标记中，并在标记EXAMPLE_PATH 中包含具有标记\example 的文件...不知道是什么错误
我必须在示例 cpp 文件中使用特殊标签吗？
您可能需要更换它。我举个例子：myproject/src 中有所有源代码，myproject/examples 中有示例（只是注释的源代码），myproject/doc 中有额外的文档文件（可能使用示例）。在配置中，INPUT 需要myproject/src 和myproject/doc。示例_PATH 应设置为 myproject/examples。

【解决方案2】：

另一种方法是使用\snippet 命令。

在你的头文件中写如下内容：

\section ex1 Example
\snippet path_to_test_class/TestClass.cpp TestClass example
\section ex2 Expected output
\snippet path_to_test_class/TestClass.cpp TestClass expected output

在 TestClass.cpp 文件中，有如下内容：

 //! [OptimizeSpeedOnTrackTest example]
 Class c;
 const double res = c.do_something();
 //! [OptimizeSpeedOnTrackTest example]
 //! [OptimizeSpeedOnTrackTest expected output]
 ASSERT_DOUBLE_EQ(5,res);
 //! [OptimizeSpeedOnTrackTest expected output]

path_to_test_class 必须在您的 EXAMPLE_PATH 中。

这将为您提供以下信息：

您的示例不仅用于文档：它们还提供测试覆盖率
您的测试运行程序（和您的编译器）为您的示例实际编译和运行提供了保证
它非常适合 TDD 工作流程

【讨论】：

使用 \sn-p 正是我所需要的。我发现每当我在要附加 \sn-p 的元素上包含 \brief 描述时，我都会得到一个没有代码的空框。
啊哈！但使用 \section 添加标题允许我也包含 \brief。
在 TestClass.cpp 中，cmets 必须匹配 sn-ps，例如// [TestClass Example]

【解决方案3】：

我在使用 @example 将示例文件包含在文档中时遇到了一些错误。这是我使用的解决方法。

将examplefile.cs 放在一个文件夹/项目中，专门用于示例代码。将该文件夹放在 Doxygen EXCLUDE 列表中（Expert->Input->EXCLUDEin Doxygen GUI 前端）和EXAMPLE_PATH（Expert->Input->EXAMPLE_PATH 在 Doxygen GUI 前端）

将此代码块放在文档文件中的某个位置（我将它放在示例所针对的文件中。）

/** @example examplefile.cs
 * A description of the example file, causes the example file to show up in 
 * Examples */

这会导致文件显示在 Doxygen 菜单的示例下，但不会显示为项目中的类/文件。

然后记录你的类/函数：

/** @brief MyClass does something
 * @details I have something more long winded to say about it.  See example 
 * in examplefile.cs: @include examplefile.cs */

这会导致示例文件在 MyClass 的文档中完整打印出来。

【讨论】：

【解决方案4】：

为 doxyfile 添加方法 EXAMPLE_PATH = dir_example \
可以连接同一文件中的所有示例，例如 example_list.h 并将其包含在 doxyfile 中 INPUT = example_list.h \

（语言 - 俄语） http://www.scale-tech.ru/SimBookmaker/doc/html/examples__list_8h_source.html 和 http://www.scale-tech.ru/SimBookmaker/doc/html/examples.html

【讨论】：