为 OpenCV 编写文档

Doxygen 概述

介绍

Doxygen?是具有许多强大功能的文档生成系统，例如：

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

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

安装

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

生成文档

• 获取 OpenCV 源代码（版本 3.0 及更高版本）
• 可选：获取OpenCV_contrib源
• 在 sources 文件夹附近创建构建目录并进入其中
• 运行 cmake（假设你把源代码放到?opencv?文件夹）：
  cmake -DBUILD_DOCS=ON ../opencv
  或者，如果您也获得了贡献源：
  cmake -DBUILD_DOCS=ON -DOPENCV_EXTRA_MODULES_PATH=../opencv_contrib/模块 ../opencv
• 运行 make：
  制作 Doxygen
• 在您喜欢的浏览器中打开?doc/doxygen/html/index.html?文件
• 测试 Python 代码：
  制作check_pylint

  注意

  必须在运行 cmake 之前安装?Pylint?才能测试 Python 代码。您可以使用系统的包管理器或使用 pip 进行安装：
  pip 安装 pylint

快速入门

注意

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

文档位置

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

• 源代码实体（如类、函数或枚举）应记录在相应的头文件中，在实体定义之前。请参阅下一节中的示例。
• 页面是放置大块文本的好地方，其中包含与任何源代码实体不直接相关的图像和代码示例。页面应位于单独的文件中，并包含在多个预定义的位置。本教程是此类页面的示例。
• 图像可以用来说明所描述的事物。图像通常位于与页面相同的位置，可以插入到文档的任何位置。
• 代码示例演示如何在实际应用程序中使用该库。每个示例都是独立的文件，代表一个简单的应用程序。这些文件的某些部分可以包含在文档和教程中，以演示函数调用和对象协作。
• BibTeX 参考文献用于创建一个通用参考书目。所有作为图书馆功能基础的科学书籍、文章和论文集都应列入此参考清单。

以下方案表示?opencv?存储库的常见文档位置：

注意

自动代码解析器查找所有头文件（“.h， .hpp”，但“.inl.hpp; .impl.hpp;_detail.hpp“） 包含在文件夹及其子文件夹中。一些特定于模块的指令（组定义）和文档应该放在?“include/opencv2/<module-name>.hpp”?文件中。

您可以将 C++ 模板实现和专用化放在 dexe 忽略的单独文件（“.impl.hpp”）中。

src?子文件夹中的文件不会被解析，因为文档主要面向库用户，而不是开发人员。但是，仍然可以通过自定义cmake脚本（doc/CMakeLists.txt）中的处理文件列表和配置文件（doc/Doxyfile.in）中的doxygen选项来生成完整的文档。

从 3.0 版本开始，所有新模块都放在opencv_contrib存储库中，它的布局略有不同：

例

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

<span style="background-color:#fbfcfd"><span style="color:#000000">/** @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);
</span></span>

在这里你可以看到：

• 特殊的 C-comment 语法表示它是 doxygen 注释

  <span style="background-color:#fbfcfd">/** ... */ </span>

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

  <span style="background-color:#fbfcfd">@brief </span>

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

  <span style="background-color:#fbfcfd">\f[ ... \f] </span>

• 命令表示以下单词是参数的名称，下面的文本是参数的描述;所有参数都放在一个列表中param

  <span style="background-color:#fbfcfd">@param </span>

• 命令启动包含对某些类、方法、页面或 URL 的引用的“另请参阅”段落。sa

  <span style="background-color:#fbfcfd">@sa </span>

生成的参考项如下所示：

“更多...”链接将带您进入函数文档：

另一个例子

单行短注释可以使用不同的注释语法：

<span style="background-color:#fbfcfd"><span style="color:#000000">//! type of line
enum LineTypes {
    FILLED  = -1,
    LINE_4  = 4, //!< 4-connected line
    LINE_8  = 8, //!< 8-connected line
    LINE_AA = 16 //!< antialiased line
};
</span></span>

这里：

• 特殊的 C++ 注释语法表示它是 doxygen 注释

  <span style="background-color:#fbfcfd">//! </span>

• 附加符号表示此注释位于记录的实体之后<

  <span style="background-color:#fbfcfd">//!< </span>

生成的文档块如下所示：

更多详情

命令前缀

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

<span style="background-color:#fbfcfd"><span style="color:#000000">@brief ...
or
\brief ...
</span></span>

注释语法

Doxygen 注释可以有不同的形式：

<span style="background-color:#fbfcfd"><span style="color:#000000">C-style:
/** ... */
or
/*! ... */

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

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

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

段落结束

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

<span style="background-color:#fbfcfd"><span style="color:#000000">@brief brief description paragraph
brief continues

new paragraph

@note new note paragraph
note paragraph continues

another paragraph
paragraph continues
</span></span>

命名

页面、锚点、组和其他命名实体在整个项目中应具有唯一名称。最好在此类标识符前面加上模块名称：

<span style="background-color:#fbfcfd"><span style="color:#000000">@page core_explanation_1 Usage explanation
@defgroup imgproc_transform Image transformations
@anchor mymodule_interesting_note
</span></span>

支持的 Markdown

Doxygen 支持带有一些扩展的 Markdown 格式。简短的语法参考如下，有关详细信息，请访问?Markdown 支持。

列表

<span style="background-color:#fbfcfd"><span style="color:#000000">Bulleted:
- item1
- item2
Numbered:
1. item1
2. item2
or
-# item1
-# item2
</span></span>

强调

<span style="background-color:#fbfcfd"><span style="color:#000000">_italic_
__bold__
use html in complex cases:
<em>"path/to/file"</em>
</span></span>

链接

<span style="background-color:#fbfcfd"><span style="color:#000000">explicit link:
[OpenCV main site](http://opencv.org)
automatic links:
<http://opencv.org>
or even:
http://opencv.org
</span></span>

图像

<span style="background-color:#fbfcfd"><span style="color:#000000">![image caption](image path)
</span></span>

头

<span style="background-color:#fbfcfd"><span style="color:#000000">Level1
======
Level2
------
### Level3
#### Level4
</span></span>

标头 ID

您可以为任何标头分配唯一标识符，以便从其他位置引用它。

<span style="background-color:#fbfcfd"><span style="color:#000000">Header {#some_unique_identifier}
------
...
See @ref some_unique_identifier for details
</span></span>

页面 ID

每个页面的开头都应有额外的 Level1 标题，其中包含页面标题和标识符：

<span style="background-color:#fbfcfd"><span style="color:#000000">Writing documentation for OpenCV {#tutorial_documentation}
================================
</span></span>

表

doxygen 文档中的示例：

<span style="background-color:#fbfcfd"><span style="color:#000000">First Header  | Second Header
------------- | -------------
Content Cell  | Content Cell
Content Cell  | Content Cell</span></span>