如何将示例集成到Doxygen文档中？

Question

我已经记录了所有的课程，现在我想集成一个使用这些课程的示例。我该怎么做？

- Tobi Weißhaar

Answer 1

您可以将示例源代码放置在doxygen配置中定义的特殊路径EXAMPLE_PATH中，并使用@example标签插入示例。

然后，Doxygen将生成一个包含示例源代码的额外页面，并从包含示例标签的类文档中设置链接。

或者，如果您想要使用小的代码片段，您可以使用@code ... @endcode插入它们。

此功能的文档在此处： doxygen documentation?

- Loebl

---

是的，我做了那个，但是额外页面中的.cpp文件是空的 :/ - Tobi Weißhaar

Doxygen 会给出任何警告或错误吗？ - Loebl

我在INPUT标签和EXAMPLE_PATH标签中包含了示例文件，其中标有\example的文件出现了错误，不知道是什么原因。 - Tobi Weißhaar

我需要在示例cpp文件中使用特殊标签吗？ - Tobi Weißhaar

我明白了……我忘记把示例cpp文件添加到EXAMPLE_PATH路径中了^^ - Tobi Weißhaar

Answer 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工作流程中使用

- Deimos

---

使用\snippet正是我所需要的。我发现，每当我在要附加\snippet的元素上包含一个\brief描述时，我得到的是一个空白框，没有任何代码。 - Scott Langham

啊哈！但是使用 \section 添加标题可以让我同时包含 \brief。 - Scott Langham

在 TestClass.cpp 中，注释必须与代码片段匹配，例如 // [TestClass Example]。 - mrtnlrsn

Answer 3

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

1. 将 examplefile.cs 文件放置在专门用于示例代码的文件夹/项目中。 2. 将该文件夹添加到 Doxygen 的 EXCLUDE 列表中（在 Doxygen GUI 前端的 Expert->Input->EXCLUDE 中），并添加到 EXAMPLE_PATH（在 Doxygen GUI 前端的 Expert->Input->EXAMPLE_PATH 中）。 3. 在已记录的文件中的某个位置（我将其放在了示例所属的文件中）添加此代码块。

/** @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的文档中完整打印出来。

- Denise Skidmore

Answer 4

1. 添加一个在doxyfile中的方法 EXAMPLE_PATH = dir_example \

2. 可以将所有示例连接到同一个文件中，例如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

- Denis