为OpenCV编写文档
Doxygen概述
介绍
Doxygen是具有很多功能的文档生成系统,如:
- 解析程序源,以产生实际和准确的文档
- 检查文档是否有错误
- 插入图像和公式
- 使用markdown语法和纯HTML进行精确的文本格式化
- 生成许多不同格式的文档
OpenCV库的现有文档已经转换为doxygen格式。
安装
请查看官方下载和安装页面。一些linux发行版也可以提供doxygen软件包。
生成文档
- 获取OpenCV源(版本3.0及更高版本)
- 可选:获取OpenCV_contrib源
- 在源文件夹附近创建构建目录并进入它
- 运行cmake(假设你把源放到opencv文件夹):
或者如果你也得到contrib来源:cmake ../opencv
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
- 在函数定义之前添加空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文档并验证结果。
更多建议: