为OpenCV编写文档

2018-08-28 18:35 更新

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 

生成的参考项目如下所示:

doxygen的-2.png

“更多...”链接将带您进入功能文档:

doxygen-1

功能文档

另一个例子

不同的注释语法可用于单行简短注释:

//! 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注释
    //!
  • 其他符号<表示此评论位于后记录实体
    // <!

生成的文档块如下所示:

doxygen-3

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}

要将整个示例文件包含在文档中,请使用includeincludelineno命令。该文件在通用样本位置进行搜索,因此您可以仅指定其名称或路径的一小部分。该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”选项:
scholarship_cite_dialog

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文档并验证结果。

参考


以上内容是否对您有帮助:
在线笔记
App下载
App下载

扫描二维码

下载编程狮App

公众号
微信公众号

编程狮公众号