为 OpenCV 编写文档(二)

常用命令

这里通过简短的示例描述了最常用的 doxygen 命令。有关可用命令的完整列表和详细说明，请访问命令参考。

基本命令

• brief?- 带有简要实体描述的段落

• param?- 函数参数的描述。

  多个相邻语句合并到一个列表中。如果在实际函数签名中找不到具有此名称的参数 - 将产生 doxygen 警告。函数可以没有记录的参数，也可以记录所有参数。

• sa?- “另请参阅”段落，包含对类、函数、页面或 URL 的引用
• 注意?- 视觉上突出显示的“注意”段落。多个相邻的语句合并到一个块中。
• return， returns?- 描述函数的返回值
• overload?- 在函数描述中添加固定文本：“这是一个重载成员函数，为方便起见而提供。它与上述函数的区别仅在于它接受的参数。
• 锚点?- 放置不可见的命名锚点，可以通过命令引用。它只能在页面中使用。ref

• ref?- 对命名部分、页面或锚点的显式引用。

  如果找不到此类实体，将生成 doxygen 警告。此命令有一个可选参数 - 链接文本。

  Doxygen 还会自动生成一些链接：如果文本包含可以在文档实体中找到的单词 - 将生成引用。可以通过在单词前面加上符号来禁用此功能。%

  <span style="background-color:#fbfcfd">Explicit reference: @ref MyClass
  Explicit named reference: @ref example_page "Example page"
  Implicit reference: cv::abc::MyClass1 or just MyClass1
  Disable implicit reference: %MyClass1</span>

• F?- 公式

  内联公式以命令为界：f$

  <span style="background-color:#fbfcfd">\f$ ... \f$</span>

  块公式 - 使用 和 命令：f[f]

  <span style="background-color:#fbfcfd">\f[ ... \f]</span>

代码包含命令

要在文档中将某些文本标记为代码，请使用?code?和?endcode?命令。

<span style="background-color:#fbfcfd"><span style="color:#000000">@code
float val = img.at<float>(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101),
                          borderInterpolate(-5, img.cols, cv::BORDER_WRAP));
@endcode
</span></span>

语法将根据当前解析的文件类型突出显示（C++ 表示?.hpp，C?表示?.h），或者您可以在大括号中手动指定它：

<span style="background-color:#fbfcfd"><span style="color:#000000">@code{.xml}
</span></span>

要将整个示例文件包含在文档中，请使用?include?和?includelineno?命令。在常见示例位置搜索该文件，因此您可以仅指定其名称或路径的短部分。includelineno?版本还显示行号，但由于包含行号，因此可以防止复制粘贴。

<span style="background-color:#fbfcfd"><span style="color:#000000">@include samples/cpp/test.cpp
</span></span>

如果要包含现有示例文件的某些部分，请使用?snippet?命令。

首先，用特殊的 doxygen 注释标记文件的所需部分：

<span style="background-color:#fbfcfd"><span style="color:#000000">//! [var_init]
int a = 0;
//! [var_init]
</span></span>

然后将以下代码片段包含在文档中：

<span style="background-color:#fbfcfd"><span style="color:#000000">@snippet samples/cpp/test.cpp var_init
</span></span>

注意

目前，大多数此类部分包含都是使用?dontinclude?命令进行的，以便与旧的 rST 文档兼容。但是，新创建的示例应包含在?snippet?命令中，因为此方法受已处理文件更改的影响较小。

切换按钮包含命令

切换按钮用于显示所选配置（例如编程语言、操作系统、IDE）。

要使用文档中的按钮，请使用?add_toggle?和?end_toggle?命令。

命令add_toggle可以是

• 常规：add_toggle{按钮名称}
• 对于C++：add_toggle_cpp
• 对于 Java：add_toggle_java
• 对于 Python：add_toggle_python

例：

<span style="background-color:#fbfcfd"><span style="color:#000000">@add_toggle{Button Name}

  text / code / doxygen commands

@end_toggle
</span></span>

例如，使用带有文本和代码片段的切换按钮：

<span style="background-color:#fbfcfd"><span style="color:#000000">### Buttons Example

@add_toggle_cpp

   Text for C++ button
   @snippet samples/cpp/tutorial_code/introduction/documentation/documentation.cpp hello_world

@end_toggle

@add_toggle_java

   Text for Java button
   @snippet samples/java/tutorial_code/introduction/documentation/Documentation.java  hello_world

@end_toggle

@add_toggle_python

   Text for Python button
   @snippet samples/python/tutorial_code/introduction/documentation/documentation.py hello_world

@end_toggle</span></span>

结果如下所示：

按钮示例

C++爪哇岛蟒

如您所见，按钮会自动添加到上一个标题下。

分组命令

所有代码实体都应放入表示 OpenCV 模块及其内部结构的命名组中，因此每个模块都应与具有相同名称的组相关联。定义组和子组的好地方是此模块的主头文件：“<module>/include/opencv2/<module>.hpp”。

注意

Doxygen 组称为“模块”，显示在“模块”页面上。

<span style="background-color:#fbfcfd"><span style="color:#000000">/**
@defgroup mymodule My great module
    optional description
@{
    @defgroup mymodule_basic Basic operations
        optional description
    @defgroup mymodule_experimental Experimental operations
        optional description
@}
*/
</span></span>

要将类和函数放入特定组中，只需将 command 添加到其文档中，或者用 command 包装整个代码块：ingroupaddtogroup

<span style="background-color:#fbfcfd"><span style="color:#000000">/** @brief Example function
    @ingroup mymodule
*/
or
/**
@addtogroup mymodule_experimental
@{
*/
... several functions, classes or enumerations here
/**
@}
*/
</span></span>

出版物参考文献

使用?cite?命令插入对参考书目页面中列出的相关出版物的引用。

首先，将发布 BibTeX 记录添加到“<opencv>/doc/opencv.bib”或“<opencv_contrib>/modules/<module>/doc/<module>.bib”文件中：

<span style="background-color:#fbfcfd"><span style="color:#000000">@ARTICLE{Bradski98,
    author = {Bradski, Gary R},
    title = {Computer vision face tracking for use in a perceptual user interface},
    year = {1998},
    publisher = {Citeseer}
}
</span></span>

注意

尽量不要添加重复的出版物，因为它可能会在以后混淆文档读者和作者。

然后使用?cite?命令进行引用：

<span style="background-color:#fbfcfd"><span style="color:#000000">@cite Bradski98
</span></span>

注意

要获得出版物的 BibTeX 记录，可以使用?Google Scholar。找到出版物后 - 点击其“引用”链接，然后选择“BibTeX”选项：

循序渐进

本节中描述的步骤可以用作文档编写过程中的清单。没有必要以相同的顺序做事，但有些步骤确实取决于前面的步骤。当然，这些步骤只是基本的指导方针，总有创造力的地方。

记录函数

1. 在函数定义之前添加空的 doxygen 注释。
2. 在开头添加简短的命令，并简要描述函数含义。
3. 添加函数的详细说明。
4. 可选：插入公式、图像和示例代码块以说明复杂案例
5. 可选：使用?param?命令描述每个参数。
6. 可选：使用?returns?命令描述函数的返回值。
7. 可选：添加“另请参阅”部分，其中包含指向类似函数或类的链接
8. 可选：添加参考书目（如果有）。
9. 测试代码。（Python：“make check_pylint”）
10. 生成 doxygen 文档并验证结果。

编写教程

1. 制定要在本教程中说明的想法。

2. 使示例应用程序足够简单，以便初学者能够理解。要简明扼要，写描述性注释，不要试图避免所有可能的运行时错误或通用。你的目标是说明这个想法。它应该适合一个源文件！

   如果要将此文件中的代码块插入到教程中，请使用特殊的 doxygen 注释标记它们（请参阅此处）。

   如果要使用多种编程语言编写本教程，请使用切换按钮获取替代注释和代码（请参阅此处）。

3. 收集申请工作的结果。它可以是“之前/之后”的图像，也可以是代表性能的一些数字，甚至是视频。

   将其保存为适当的格式，以便稍后在本教程中使用：

   • 要保存简单的图形状图像，请使用无损“.png”格式。
   • 对于类似照片的图像 - 有损“.jpg”格式。
   • 数字将以纯文本形式插入，可能格式化为表格。
   • 视频应上传到 YouTube。
4. 在相应的位置（请参阅此处）创建新的教程页面（“.markdown”-file），并将所有图像文件放在其附近（或“images”子目录中）。还要放置您的示例应用程序文件，并确保在 cmake 步骤上启用选项时，它与 OpenCV 库一起编译。-DBUILD_EXAMPLES=ON
5. 修改您的新页面：
   • 添加页面标题和标识符，通常以“tutorial_”为前缀（请参阅此处）。您可以使用标识符添加指向上一教程和下一教程的链接

     <span style="background-color:#fbfcfd">@prev_tutorial{identifier}
     @next_tutorial{identifier}</span>

     警告

     不要写井号标签 （#），例如： 不正确： 正确：

     <span style="background-color:#fbfcfd">@prev_tutorial{#tutorial_documentation} </span>

     <span style="background-color:#fbfcfd">@prev_tutorial{tutorial_documentation} </span>

   • 添加您的想法和教程目标的简要描述。
   • 描述您的程序和/或其有趣的部分。

   • 描述您的结果，插入以前添加的图像或其他结果。

     要添加 youtube 视频，例如 www.youtube.com/watch?v=?ViPN810E0SU，请使用?youtube{Video ID}：

     <span style="background-color:#fbfcfd">@youtube{ViPN810E0SU}</span>

   • 添加参考书目（如果有）（见此处）。

6. 将新创建的教程添加到相应的目录中。只需找到包含所需表的“table_of_content_*.markdown”文件，并在其中放置类似于现有记录的新记录。

   它只是一个带有特殊子页面命令的列表项，它将页面标记为子页面并将其放入现有页面层次结构中。另请注意列表项缩进、段落之间的空行和特殊的斜体标记。

7. 生成 doxygen 文档并验证结果。