为OpenCV编写文档

Doxygen概述

介绍

Doxygen是具有很多功能的文档生成系统，如：

• 解析程序源，以产生实际和准确的文档
• 检查文档是否有错误
• 插入图像和公式
• 使用markdown语法和纯HTML进行精确的文本格式化
• 生成许多​​不同格式的文档

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

安装

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

生成文档

• 获取OpenCV源（版本3.0及更高版本）
• 可选：获取OpenCV_contrib源
• 在源文件夹附近创建构建目录并进入它
• 运行cmake（假设你把源放到opencv文件夹）：

  cmake ../opencv

  或者如果你也得到contrib来源：

  cmake -DOPENCV_EXTRA_MODULES_PATH = .. / opencv_contrib / modules ../opencv

• 运行make：使doxygen
• 在您最喜欢的浏览器中打开doc / doxygen / html / index.html文件
• 测试你的Python代码：

make check_pylint

快速开始

注意

这些说明特定于OpenCV库文档，其他项目可以使用不同的布局方案和文档协议。

文档位置

从许多不同的地方收集整个文件：

• 源代码实体，如类，函数或枚举，应在相应的头文件中记录，正确的实体定义。请参见下一节中的示例。
• 页面是放置大片文字的好地方，图像和代码示例不直接与任何源代码实体连接。页面应位于单独的文件中，并包含在几个预定义的位置。本教程是此类页面的示例。
• 图像可以用来说明描述的东西。通常位于与页面相同的位置，图像可以插入文档的任何位置。
• 代码示例显示了如何在实际应用中使用库。每个样本都是自包含的文件，代表一个简单的应用程序。这些文件的一部分可以包含在文档和教程中，以演示函数调用和对象协作。
• BibTeX引用用于创建一个常用的参考书目。作为图书馆功能的基础的所有科学书籍，文章和诉讼应作为参考清单。

以下方案代表了opencv存储库的常见文档：

<opencv>
├── doc             - doxygen config files, root page (root.markdown.in), BibTeX file (opencv.bib)
│   ├── tutorials       - tutorials hierarchy (pages and images)
│   └── py_tutorials    - python tutorials hierarchy (pages and images)
├── modules
│   └── <modulename>
│       ├── doc         - documentation pages and images for module
│       └── include     - code documentation in header files
└── samples         - place for all code examples
    ├── cpp
    │   └── tutorial_code   - place for tutorial code examples
    └── ...

注意

自动代码解析器在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         - documentation pages and images, BibTeX file (<modulename>.bib)
        ├── include     - code documentation in header files
        ├── samples     - place for code examples for documentation and tutorials
        └── tutorials   - tutorial pages and images

Example

要为函数，类和其他实体添加文档，只需在其定义之前插入特殊注释。喜欢这个：

/** @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-comment语法表示它是doxygen注释
  

/ ** ... * / 

• 命令brief表示以下段落是简要说明
  

@brief 

• 空行表示段落结束
• TeX公式f[与f]命令之间

  \ 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注释

  //！

• 其他符号<表示此评论位于后记录实体

  // <！

生成的文档块如下所示：

Enumeration documentation

更多细节

命令前缀

Doxygen命令以@或\符号开始：

@brief ...
or
\brief ...

评论语法

Doxygen评论可以有不同的形式：

C-style:
/** ... */
or
/*! ... */

C++-style
//! ...
or
/// ...

Lines can start with '*':
/**
 * ...
 * ...
 */

Can be placed after documented entity:
//!< ...
/**< ... */

段落结束

要结束段落，请插入空行或任何命令开始新段落：

@brief brief description paragraph
brief continues

new paragraph

@note new note paragraph
note paragraph continues

another paragraph
paragraph continues

命名

页面，锚点，组和其他命名实体在整个项目中应该有唯一的名称。将此标识符与模块名称进行前缀是一个好主意：

@page core_explanation_1 Usage explanation
@defgroup imgproc_transform Image transformations
@anchor mymodule_interesting_note

支持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](http://opencv.org)
automatic links:
<http://opencv.org>
or even:
http://opencv.org

图片

![image caption](image path)

headers

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命令在这里用简短的例子进行描述。有关可用命令和详细描述的完整列表，请访问命令参考。

基本命令

• 简短的段落，简要的实体描述
• 参数 - 函数参数的描述。多个相邻语句合并成一个列表。如果在实际功能签名中找不到带有该名称的参数，则会产生doxygen警告。功能可以没有文件参数，都应该记录。
• sa - “另请参见”段落，包含对类，函数，页面或URL的引用
• 注意 - 视觉突出显示“注”段。多个相邻语句合并成一个块。
• return，returns - 描述函数的返回值
• 过载 - 将固定文本添加到函数描述中：“为了方便起见，这是一个重载的成员函数，它与上述函数的区别仅在于它接受的参数。
• 锚 - 不可见的命名锚，可以通过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
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命令中，因为此方法受处理文件中更改的影响较小。

切换按钮包含命令

切换按钮用于显示所选配置（例如编程语言，操作系统，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

结果如下所示：

按钮示例

C ++

C ++文本按钮

std :: cout << “Hello World！” ;

Java

文本为Java按钮

        System.out.println（“Hello World！”）;

Python

Python的文本按钮

print('Hello world!')

您可以看到，按钮将在上一个标题下自动添加。

分组命令

所有代码实体都应该被放入代表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学术搜索。一旦找到出版物 - 按照“引用”链接，然后选择“BibTeX”选项：

Step-by-step

本文中描述的步骤可在文档编写过程中用作检查表。没有必要按照同样的顺序做事情，但有些步骤真的取决于以前的事情。当然，这些步骤只是基本的指导方针，总是有创意的地方。

记录功能

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

写教程

1. 制定教程中说明的想法。
2. 使示例应用程序，简单到足以被开发人员理解。做一个简明扼要的并且写描述性的注释，不要试图避免每一个可能的运行时错误或使通用效用。你的目标是说明这个想法。它应该适合一个源文件！如果要将此文件中的代码块插入到教程中，请使用特殊的doxygen注释来标记它们（请参阅此处）。如果要用多种编程语言编写教程，请使用切换按钮进行备用注释和代码（参见此处）。
3. 收集应用工作的结果。它可以是“之前/之后”图像或一些表示性能的数字，甚至视频。保存适当的格式供以后在教程中使用：为了保存简单的图形图像，使用无损“.png”格式。照片般的图像 - lossy“.jpg”格式。数字将作为纯文本插入，可能格式化为表格。视频应该在YouTube上上传。
4. 在相应位置创建新的教程页面（“.markdown” -file）（请参阅此处），并将所有图像文件放在其附近（或“images”子目录中）。还要放置您的示例应用程序文件，并确保-DBUILD_EXAMPLES=ON在cmake步骤上启用选项时与OpenCV库一起编译。
5. 修改您的新页面：

@prev_tutorial{identifier}
@next_tutorial{identifier}

警告

不要不写主题标签（＃） ，例如：
不正确的：

@prev_tutorial {} #tutorial_documentation 

      正确：

@prev_tutorial {} tutorial_documentation 

• 添加简要描述您的想法和教程目标。
• 描述你的节目和/或其有趣的作品。
• 描述您的结果，插入以前添加的图像或其他结果。要添加YouTube视频，例如www.youtube.com/watch?v= ViPN810E0SU，请使用youtube { Video ID }：

@youtube {} ViPN810E0SU

添加书目参考文献（参见这里）。

    6. 将新创建的教程添加到相应的目录中。只需找到“table_of_content _ *。markdown”文件，并附上所需的表格，并将其中的新记录与现有记录类似。

-   @subpage tutorial_windows_visual_studio_image_watch

    _Languages:_ C++, Java, Python

    _Compatibility:_ \>= OpenCV 2.4

    _Author:_ Wolf Kienzle

    You will learn how to visualize OpenCV matrices and images within Visual Studio 2012.

正如你可以看到的，它只是一个列表项，其中有一个特殊的subpage命令，它将你的页面标记为一个小孩，并把它放到现有的页面层次结构中。添加兼容性信息，作者列表和简短描述。还要注意列表项缩进，段落之间的空行和特殊的斜体标记。

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

参考

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