前一教程： 入门图像
下一教程： 过渡指南


原作者	Maksim Shabunin
兼容性	OpenCV >= 3.0

Doxygen 概览

简介

Doxygen 是一款文档生成系统，具有众多强大功能，例如

解析程序源代码以生成实际且准确的文档
检查文档中的错误
插入图像和公式
使用 Markdown 语法和纯 HTML 进行精确的文本格式化
以多种不同的格式生成文档

现有的 OpenCV 库文档已转换为 doxygen 格式。

安装

请查看官方下载和安装页面。一些 Linux 发行版还可以提供 doxygen 包。

生成文档

获取 OpenCV 源代码（版本 3.0 及更高版本）
可选：获取 OpenCV_contrib 源代码
在源文件夹附近创建构建目录并进入其中
运行 cmake（假设你将源代码放在 opencv 文件夹中）
cmake -DBUILD_DOCS=ON ../opencv

或者，如果你也获得了 contrib 源代码
cmake -DBUILD_DOCS=ON -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/modules ../opencv
运行 make
make doxygen
在你最喜爱的浏览器中打开 doc/doxygen/html/index.html 文件
测试你的 Python 代码
make check_pylint

注意
在运行 cmake 之前，必须安装 Pylint 才能测试 Python 代码。你可以使用系统包管理器或 pip 安装
pip install pylint

快速入门

注意: 这些指导针都特别针对 OpenCV 库文档，其他项目可以使用不同的布局方案和记录商定。

文档位置

整体文档从许多不同地方收集

源代码实体，如类、函数或枚举，应该记录在相应的头文件中，实体定义前。查看下一部分的示例。
页面是放置图像段落、代码示例的好场所，这些示例与任何源代码实体没有任何直接联系。页面应该放置在单独的文件中，并包含在几个预定义的地方。本教程就是这样一个页面的示例。
图像可用于说明所述内容。图像通常放置在与页面相同的地方，还可以插入到文档的任何地方。
代码示例展示如何在真实应用程序中使用库。每个示例都是独立的文件，代表一个简单的应用程序。这些文件的某些部分可以被包含在文档和教程中，以演示函数调用和对象协同。
BibTeX 引用用于创建一个公用书目。所有作为库功能基础的科学书籍、文章和诉讼活动都应放在此引用列表中。

以下方案表示 opencv 存储库的通用文档放置

<opencv>
├── doc - doxygen 配置文件，根页面 (root.markdown.in)，BibTeX 文件 (opencv.bib)
│   ├── tutorials - 教程层次结构（页面和图像）
│   └── py_tutorials - python 教程层次结构（页面和图像）
├── modules
│   └── <modulename>
│      ├── doc - 模块的文档页面和图像
│      └── include - 头文件中的代码文档
└── samples - 所有代码示例的位置
├── cpp
│ └── tutorial_code - 教程代码示例的位置
└── ...

注意: 自动代码解析器在 include 文件夹及其子文件夹中查找所有头文件（".h, .hpp"，除了 ".inl.hpp; .impl.hpp; _detail.hpp"）。某些模块特定的指令（组定义）和文档应该放入 "include/opencv2/<module-name>.hpp" 文件。; 你可以将 C++ 模板实现和特殊格式放入被 doxygen 忽略的单独文件中（".impl.hpp"）。; src 子文件夹中的文件不会被解析，因为文档主要面向库用户，而非开发者。但是仍然可以通过在 cmake 脚本 (doc/CMakeLists.txt) 和在其配置文件 (doc/Doxyfile.in) 中的 doxygen 选项中定制已处理文件列表来生成完整文档。

自 3.0 版本后，所有新模块都被放入 opencv_contrib 存储库，它的布局略有不同

<opencv_contrib>
└── modules
└── <modulename>
├── doc - 文档页面和图像、BibTeX 文件 (<modulename>.bib)
├── include - 头文件中的代码文档
├── 示例 - 用于文档和教程的代码示例位置
└── 教程 - 教程页面和图片

示例

如需为函数、类和其他实体添加文档，只需在其定义之前插入特殊注释。如下所示

/** @brief Calculates the exponent of every array element.

The function exp calculates the exponent of every element of the input array:
\f[ \texttt{dst} [I] = e^{ src(I) } \f]

The maximum relative error is about 7e-6 for single-precision input and less than 1e-10 for
double-precision input. Currently, the function converts denormalized values to zeros on output.
Special values (NaN, Inf) are not handled.

@param src input array.
@param dst output array of the same size and type as src.

@sa log , cartToPolar , polarToCart , phase , pow , sqrt , magnitude
*/
CV_EXPORTS_W void exp(InputArray src, OutputArray dst);

在此处可以看到

特殊的 C 注释语法表示它是一个 doxygen 注释
```
/** ... */ 
```
命令 brief 表示后面的段落是一个简要说明
```
@brief 
```
空行表示段落结束
f[ 和 f] 命令之间的 TeX 公式
```
\f[ ... \f] 
```
命令 param 表示后面的单词是参数名称，后面的文本是该参数的说明；所有参数都放置在一个列表中
```
@param 
```
命令 sa 开始“另请参见”段落，其中包含对某些类、方法、页面或 URL 的引用。
```
@sa 
```

生成的引用项目如下所示：

“更多...”链接将您带到函数文档：

另一个示例

可对单行短注释使用不同的注释语法

//! type of line
enum LineTypes {
    FILLED  = -1,
    LINE_4  = 4, //!< 4-connected line
    LINE_8  = 8, //!< 8-connected line
    LINE_AA = 16 //!< antialiased line
};

此处

特殊的 C++ 注释语法表示它是一个 doxygen 注释
```
//! 
```
附加符号 < 表示此注释位于已记录实体之后
```
//!< 
```

生成的文档块如下所示：

支持的 Markdown

Doxygen 支持 Markdown 格式以及一些扩展。以下简要描述了语法引用，有关详细信息，请访问 Markdown 支持。

列表

Bulleted:
- item1
- item2
Numbered:
1. item1
2. item2
or
-# item1
-# item2

强调

_italic_
__bold__
use html in complex cases:
<em>"path/to/file"</em>

链接

explicit link:
[OpenCV main site](https://opencv.ac.cn)
automatic links:
<https://opencv.ac.cn>
or even:
https://opencv.ac.cn

图片

![image caption](image path)

标题

Level1
======
Level2
------
### Level3
#### Level4

标题 ID

可以向任何标题分配唯一标识符，以便从此处引用。

Header {#some_unique_identifier}
------
...
See @ref some_unique_identifier for details

页面 ID

每个页面在开头应有附加的第 1 级标题，其中包含页面标题和标识符

Writing documentation for OpenCV {#tutorial_documentation}
================================

表格

Doxygen 文档的示例

First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell

常用命令

这里用简短的示例介绍使用频率最高的 doxygen 命令。要了解完整可用命令和详细描述，请访问命令参考。

基本命令

brief - 带有简短实体描述的段落
param - 函数参数的描述。

多个相邻的语句被合并成一个列表。如果在实际函数签名中找不到具有此名称的参数，则会生成 doxygen 警告。函数可以没有已记录参数，也可以记录所有参数。
sa - “另请参见”段落，包含类、函数、页面或 URL 的引用
note - 显示突出为“注意”的段落。多个相邻的语句被合并成一个块。
return、returns - 描述函数的返回值
overload - 向函数描述中添加固定文本：“这是一个重载成员函数，为方便而提供。它与上述函数仅接受的参数不同。”
anchor - 放置可以由 ref 命令引用的不可见命名锚点。只能在页面中使用。
ref - 对命名部分、页面或锚点的显式引用。

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

Doxygen 还会自动生成一些链接：如果文本包含可查找到记录实体的单词，则会生成引用。可以通过在单词前加 % 符号来禁用此功能。
```
Explicit reference: @ref MyClass
Explicit named reference: @ref example_page "Example page"
Implicit reference: cv::abc::MyClass1 or just MyClass1
Disable implicit reference: %MyClass1
```
f - 公式

内联公式用 f$ 命令包围
```
\f$ ... \f$
```
块公式 - 用 f[ 和 f] 命令
```
\f[ ... \f]
```

代码包含命令

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

@code
float val = img.at<float>(borderInterpolate(100, img.rows, cv::BORDER_REFLECT_101),
                          borderInterpolate(-5, img.cols, cv::BORDER_WRAP));
@endcode

语法会根据当前解析的文件类型（C++ 表示 .hpp，C 表示 .h）高亮显示，也可以在花括号中手动指定。

@code{.xml}

若要将整个示例文件包含到文档中，则使用 include 和 includelineno 命令。该文件在常见样本位置中搜索，因此你只需指定其名称或路径的一部分。includelineno 版本还会显示行号，但会阻止拷贝粘贴，因为包括了行号。

@include samples/cpp/test.cpp

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

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

//! [var_init]
int a = 0;
//! [var_init]

然后将此代码段包含到文档中

@snippet samples/cpp/test.cpp var_init

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

切换按钮包含命令

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

若要将按钮用于文档中，请使用add_toggle 和 end_toggle 命令。

add_toggle 命令可以

通用：add_toggle{按钮名称}
适用于 C++：add_toggle_cpp
适用于 Java：add_toggle_java
适用于 Python：add_toggle_python

示例

@add_toggle{Button Name}

  text / code / doxygen commands

@end_toggle

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

### 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

结果如下所示

按钮示例

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

分组命令

所有代码实体均应放入代表 OpenCV 模块及其内部结构的命名组中，因此应将每个模块与具有相同名称的组关联起来。定义组和子组的最佳位置是此模块的主头文件："<module>/include/opencv2/<module>.hpp"。

注意: Doxygen 组称为“模块”，并显示在“模块”页面中。

/**
@defgroup mymodule My great module
    optional description
@{
    @defgroup mymodule_basic Basic operations
        optional description
    @defgroup mymodule_experimental Experimental operations
        optional description
@}
*/

若要将类和函数放入特定组中，只需将其文档添加到 ingroup 命令或使用 addtogroup 命令包装整个代码块即可

/** @brief Example function
    @ingroup mymodule
*/
or
/**
@addtogroup mymodule_experimental
@{
*/
... several functions, classes or enumerations here
/**
@}
*/

出版物参考

使用cite 命令插入对参考文献页面中所列相关出版物的引用。

首先，将出版物的 BibTeX 记录添加到 "<opencv>/doc/opencv.bib" 或 "<opencv_contrib>/modules/<module>/doc/<module>.bib" 文件

@ARTICLE{Bradski98,
    author = {Bradski, Gary R},
    title = {Computer vision face tracking for use in a perceptual user interface},
    year = {1998},
    publisher = {Citeseer}
}

注意: 尽量不要添加重复的出版物，因为这可能会让后来的文档阅读者和编写者感到困惑。

然后使用 cite 命令添加引用

@cite Bradski98

注意: 要获取出版物的 BibTeX 记录，可以使用 Google Scholar。找到出版物后，请点击“引用”链接，然后选择“BibTeX”选项：

分步操作

本节中所述的步骤可用作编写文档过程中的检查表。不一定按相同的顺序执行，但有些步骤确实取决于先前的步骤。当然，这些步骤只是基本指南，始终有发挥创造力的余地。

记录函数

添加在函数定义前面空 doxygen 注释。
在开头添加brief 命令，并简要说明函数的含义。
添加函数的详细说明。
可选：插入公式、图像和示例代码块来说明复杂情况
可选：使用 param 命令描述各个变量。
可选：使用 returns 命令描述各个函数的返回值。
可选：添加“另请参阅“部分，其中包含类似函数或类的链接
可选：添加任何参考书目。
测试你的代码（Python: "make check_pylint")
生成 Doxygen 文档并验证结果。

撰写教程

构思教程中要阐述的想法。
制作示例应用程序，简单到初学者也能懂。简明扼要，撰写描述性的注释，不要试图规避任何可能出现的运行时错误或制作通用实用程序。目的是阐述想法，且应包含在一个源文件内！

如果你想将此文件中的代码块插入教程内，请使用特殊的 Doxygen 注释对其进行标记（参见此处）。

如果你想使用多种编程语言撰写教程，请使用主题切换按钮来选择不同的注释和代码（参见此处）。
收集应用程序作业结果。可采用“前后”图像，或一些代表性能的数字，甚至视频。

以适当格式保存，以便稍后在教程中使用
- 若要保存图像类似的简单图形，请采用无损“.png”格式。
- 若要保存图像类似的照片，请采用有损“.jpg”格式。
- 数字应以纯文本形式插入，可能以表格格式排列。
- 视频应上传到 YouTube。
在相应位置创建新的教程页面（“.markdown” 文件）（参见此处），并将所有图片文件放置在附近（或放在“images”子目录中）。此外，请添加示例应用程序文件，并确保当在 cmake 步骤中启用 -DBUILD_EXAMPLES=ON 选项时，将其与 OpenCV 库一起编译。
修改新页面
- 添加页面标题和标识符，通常以 “tutorial_” 开头（参见此处）。你可以使用标识符添加上一个教程和下一个教程的链接
```
@prev_tutorial{identifier}
@next_tutorial{identifier}
```
  警告
  不要写 标签 (#)，例如
  错误
```
@prev_tutorial{#tutorial_documentation} 
```
  正确
```
@prev_tutorial{tutorial_documentation} 
```
- 简要描述你的想法和教程目标。
- 描述你的程序和/或其有趣的部分。
- 描述你的结果，插入之前添加的图像或其他结果。
  
  若要添加 YouTube 视频，例如 www.youtube.com/watch?v= ViPN810E0SU，请使用 youtube{视频 ID}
```
@youtube{ViPN810E0SU}
```
- 如有任何参考书目，请添加（参见此处）。
将新创建的教程添加到相应的内容表中。只需查找带有所需表格的 “table_of_content_*.markdown” 文件，并在其中按照现有记录添加新记录。

它仅仅是一个带有特殊子页面指令的列表项，该指令将你的页面标记为子页面，并将其放置到现有的页面层次结构中。此外，请注意列表项缩进、段落之间的空行以及特殊的斜体标记。
生成 Doxygen 文档并验证结果。

参考资料

Doxygen - Doxygen 主页
文档基础知识 - 如何在代码中包含文档
Markdown 支持 - 支持的语法和扩展
公式支持 - 如何加入公式
支持的公式命令 - HTML 公式使用 MathJax 脚本进行渲染
命令参考 - 支持的命令及其参数

目录