Doxygen入门指南：从注释到自动文档

Doxygen 入门指南：从注释到自动文档

Doxygen 是一款用于生成代码文档的工具，支持 C、C++、Python 等多种语言，尤其适合 C/C++ 项目。本文将介绍如何使用 Doxygen 规范注释并生成 API 文档。

一、安装 Doxygen

1. Windows

下载安装包：Doxygen 官网（选择 doxygen-<version>.setup.exe）
安装时勾选 doxywizard（图形化配置工具，推荐新手使用）

2. Linux

bash 复制代码

# Ubuntu/Debian
sudo apt-get install doxygen graphviz  # graphviz 用于生成图表
# CentOS
sudo yum install doxygen graphviz

3. macOS

bash 复制代码

brew install doxygen graphviz

二、基本注释规则

Doxygen 通过识别特定格式的注释生成文档，核心是 /\** ... \*/ 风格的注释块，配合标签（@tag）描述代码信息。

1. 函数 / 方法注释

cpp 复制代码

/**
 * @brief 计算两个整数的和
 * 
 * 支持正数、负数和零的加法运算，返回结果不会溢出（假设输入在 int 范围内）
 * 
 * @param a 第一个加数
 * @param b 第二个加数
 * @return 两数之和（int 类型）
 * @note 若输入超出 int 范围，可能导致未定义行为
 */
int add(int a, int b) {
    return a + b;
}

2. 类 / 结构体注释

cpp 复制代码

/**
 * @brief 表示二维坐标的结构体
 * 
 * 存储 x 和 y 坐标，提供基础的坐标运算方法
 */
struct Point {
    int x;  ///< x 坐标（成员变量注释用 ///<）
    int y;  ///< y 坐标

    /**
     * @brief 初始化坐标
     * @param x_ x 坐标值
     * @param y_ y 坐标值
     */
    Point(int x_, int y_) : x(x_), y(y_) {}
};

3. 文件头部注释

每个 .h 或 .cpp 文件建议添加头部注释，说明文件功能：

cpp 复制代码

/**
 * @file math_utils.h
 * @brief 数学工具函数集合
 * 
 * 包含加法、减法、乘法等基础运算，以及向量、矩阵操作
 * @author 你的名字
 * @date 2024-05-01
 */

三、常用标签速查表

标签	用途	示例
`@brief`	简短描述（一句话功能说明）	`@brief 计算绝对值`
`@param`	描述函数参数	`@param num 待计算的数字`
`@return`	描述返回值	`@return 非负结果`
`@note`	补充说明（注意事项）	`@note 输入不能为nullptr`
`@warning`	警告信息（危险操作）	`@warning 此函数会修改原始数组`
`@file`	标记文件注释	`@file string_utils.h`
`@author`	作者信息	`@author 张三 <zhangsan@example.com>`
`@date`	日期	`@date 2024-05-01`
`@see`	关联内容（参考其他函数 / 类）	`@see add()`

四、生成文档步骤

方法 1：使用 doxywizard（图形化工具）

打开 doxywizard（Windows 可在开始菜单找到，Linux/macOS 终端输入 doxywizard）
Step 1: 配置输入输出
- Working directory：选择项目根目录
- Input：添加代码目录（如 ./src）
- Output directory：设置文档输出路径（如 ./docs）
Step 2: 选择输出格式
- 在 Output 标签页勾选 HTML（必选）和 LaTeX（如需 PDF）
Step 3: 生成文档
- 点击 Run doxygen，等待生成完成
- 打开 ./docs/html/index.html 查看文档

方法 2：使用命令行（推荐熟练后使用）

在项目根目录创建配置文件 Doxyfile :
bash 复制代码
```
doxygen -g Doxyfile  # 生成默认配置
```

编辑Doxyfile关键配置（可选，默认也可生成文档）：

ini 复制代码

PROJECT_NAME           = "OL库"  # 项目名称
INPUT                  = ./src   # 代码目录
OUTPUT_DIRECTORY       = ./docs  # 文档输出目录
RECURSIVE              = YES     # 递归处理子目录
GENERATE_HTML          = YES     # 生成HTML文档

生成文档：
bash 复制代码
```
doxygen Doxyfile  # 执行配置文件
```

下面是采用我开源的OL库生成的开发文档示例（项目地址：https://github.com/1613661434/OL.git）

五、高级技巧

生成调用关系图

在 Doxyfile 中开启：
ini 复制代码
```
HAVE_DOT               = YES
CALL_GRAPH             = YES
CALLER_GRAPH           = YES
```
需提前安装 graphviz（见步骤一）。
忽略不需要的代码

用 /// @cond 和 /// @endcond 包裹无需生成文档的代码：
cpp 复制代码
```
/// @cond
// 内部辅助函数，不对外暴露
static void helper() {}
/// @endcond
```

集成到 CMake 构建流程

在 CMakeLists.txt 中添加：

cmake 复制代码

find_package(Doxygen)
if(DOXYGEN_FOUND)
    add_custom_target(docs
        COMMAND doxygen Doxyfile
        WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}
        COMMENT "生成API文档"
    )
endif()

之后可通过 make docs（Linux）或 cmake --build . --target docs 生成文档。

六、常见问题

注释不生效？
确保注释块以 /** 开头（不是 /* 或 //），且标签拼写正确（区分大小写）。
中文乱码？
在 Doxyfile 中设置 DOXYFILE_ENCODING = UTF-8 和 OUTPUT_LANGUAGE = Chinese。
文档缺少函数？
检查函数是否在 .h 头文件中声明（Doxygen 通常优先解析头文件）。