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

注意
必须安装Pylint才能运行cmake来测试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 - 头文件中的代码文档
├── samples - 文档和教程的代码示例位置
└── tutorials - 教程页面和图像

示例

要为函数、类和其他实体添加文档，只需在其定义之前插入特殊的注释。像这样

/** @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

每个页面开头应添加一个额外的 Level1 标题，包含页面标题和标识符

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

语法将根据当前解析的文件类型（.hpp的C++，.h的C）进行高亮显示，或者您可以在花括号中手动指定它。

@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命令包含，因为此方法受处理文件更改的影响较小。

切换按钮包含命令

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

要在文档中使用按钮，可以使用add_toggle和end_toggle命令。

add_toggle命令可以是：

通用：add_toggle{Button Name}
对于 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”文件，并在其中添加与现有记录类似的新记录。

它只是一个列表项，带有特殊的subpage命令，该命令将您的页面标记为子页面并将其放置到现有页面层次结构中。还要注意段落之间的列表项缩进、空行和特殊的斜体标记。
生成 Doxygen 文档并验证结果。

参考文献

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


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

目录