为OpenCV编写文档
Doxygen概述
介绍
Doxygen是具有很多功能的文档生成系统，如：
- 解析程序源，以产生实际和准确的文档
- 检查文档是否有错误
- 插入图像和公式
- 使用markdown语法和纯HTML进行精确的文本格式化
- 生成许多不同格式的文档
OpenCV库的现有文档已经转换为doxygen格式。
安装
请查看官方下载和安装页面。一些linux发行版也可以提供doxygen软件包。
生成文档
- 获取OpenCV源（版本3.0及更高版本）
- 可选：获取OpenCV_contrib源
- 在源文件夹附近创建构建目录并进入它
- 运行cmake（假设你把源放到opencv文件夹）：
或者如果你也得到contrib来源：cmake ../opencvcmake -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 imagesExample
要为函数，类和其他实体添加文档，只需在其定义之前插入特殊注释。喜欢这个：
/** @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
图片
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
- 在函数定义之前添加空doxygen注释。
- 在开始时添加简短的功能意义简短的命令。
- 添加功能的详细说明。
- 可选：插入示例代码的公式，图像和块，以说明复杂的情况
- 可选：使用param命令描述每个参数。
- 可选：使用returns命令描述函数的返回值。
- 可选：添加“参见”部分，其中包含类似功能或类的链接
- 可选：添加书目参考文献。
- 测试你的代码 （Python：“make check_pylint”）
- 生成doxygen文档并验证结果。
- 制定教程中说明的想法。
- 使示例应用程序，简单到足以被开发人员理解。做一个简明扼要的并且写描述性的注释，不要试图避免每一个可能的运行时错误或使通用效用。你的目标是说明这个想法。它应该适合一个源文件！如果要将此文件中的代码块插入到教程中，请使用特殊的doxygen注释来标记它们（请参阅此处）。如果要用多种编程语言编写教程，请使用切换按钮进行备用注释和代码（参见此处）。
- 收集应用工作的结果。它可以是“之前/之后”图像或一些表示性能的数字，甚至视频。保存适当的格式供以后在教程中使用：为了保存简单的图形图像，使用无损“.png”格式。照片般的图像 - lossy“.jpg”格式。数字将作为纯文本插入，可能格式化为表格。视频应该在YouTube上上传。
- 在相应位置创建新的教程页面（“.markdown” -file）（请参阅此处），并将所有图像文件放在其附近（或“images”子目录中）。还要放置您的示例应用程序文件，并确保-DBUILD_EXAMPLES=ON在cmake步骤上启用选项时与OpenCV库一起编译。
- 修改您的新页面：
本文中描述的步骤可在文档编写过程中用作检查表。没有必要按照同样的顺序做事情，但有些步骤真的取决于以前的事情。当然，这些步骤只是基本的指导方针，总是有创意的地方。
记录功能
写教程
@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文档并验证结果。