OpenCV项目文档编写指南：Doxygen文档生成与编写规范-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00749/article/details/148323320

OpenCV项目文档编写指南：Doxygen文档生成与编写规范

opencv 项目地址: https://gitcode.com/gh_mirrors/op/opencv

概述

在OpenCV项目中，文档是帮助开发者理解和使用库功能的重要资源。本文将详细介绍如何使用Doxygen工具为OpenCV项目生成和编写高质量的文档。

Doxygen简介

Doxygen是一个功能强大的文档生成系统，具有以下特点：

能够解析源代码生成准确的API文档
支持文档错误检查
可插入图片和数学公式
支持Markdown和HTML格式
能生成多种格式的文档输出

OpenCV从3.0版本开始全面采用Doxygen格式来管理项目文档。

安装Doxygen

要生成OpenCV文档，首先需要安装Doxygen工具。可以从Doxygen官网获取安装包，或者通过Linux发行版的包管理器安装。

文档生成步骤

获取OpenCV源代码（3.0或更高版本）
可选：获取OpenCV_contrib源代码
在源代码目录旁创建构建目录并进入

运行CMake配置：

cmake -DBUILD_DOCS=ON ../opencv

如果包含contrib模块：

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

生成文档：
```
make doxygen
```
在浏览器中打开生成的HTML文档

文档编写规范

文档位置

OpenCV文档分布在多个位置：

源代码：类、函数等实体的文档直接写在对应的头文件中
页面文档：长篇说明文档放在单独的Markdown文件中
图片：用于说明文档的图片
代码示例：演示用法的完整代码文件
参考文献：使用BibTeX格式管理

基本语法示例

函数文档示例：

/** @brief 计算数组每个元素的指数

函数exp计算输入数组中每个元素的指数：
\f[ \texttt{dst} [I] = e^{ src(I) } \f]

单精度输入的最大相对误差约为7e-6，双精度输入小于1e-10。
当前函数将非规格化值输出为零，不处理特殊值(NaN, Inf)。

@param src 输入数组
@param dst 输出数组，大小和类型与src相同

@sa log, cartToPolar, polarToCart, phase, pow, sqrt, magnitude
*/
CV_EXPORTS_W void exp(InputArray src, OutputArray dst);

枚举文档示例：

//! 线条类型
enum LineTypes {
    FILLED  = -1,
    LINE_4  = 4, //!< 4连通线
    LINE_8  = 8, //!< 8连通线
    LINE_AA = 16 //!< 抗锯齿线
};

常用Doxygen命令

基本命令：
- @brief：简短描述
- @param：参数说明
- @return：返回值说明
- @sa："参见"部分
- @note：注意事项
代码相关命令：
- @code...@endcode：内联代码块
- @include：包含完整示例文件
- @snippet：包含文件片段
分组命令：
- @defgroup：定义模块分组
- @ingroup：将实体加入分组
文献引用：
- @cite：引用参考文献