Doxygen 使用教学

发表于 更新于 分类于 本文字数： 1k 阅读时长 ≈ 4 分钟
生成代码文档的工具

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

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

一、安装 Doxygen

1. Windows

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

2. Linux

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

3. macOS

1
brew install doxygen graphviz

二、基本注释规则

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

1. 函数 / 方法注释

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

2. 类 / 结构体注释

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/**
 * @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 文件建议添加头部注释，说明文件功能：

1
2
3
4
5
6
7
8
/**
 * @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（图形化工具）

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

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

  1. 在项目根目录创建配置文件 Doxyfile :

    1
    doxygen -g Doxyfile  # 生成默认配置

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

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

  3. 生成文档：

    1
    doxygen Doxyfile  # 执行配置文件

五、高级技巧

  1. 生成调用关系图
    在 Doxyfile 中开启：

    1
    2
    3
    HAVE_DOT               = YES
    CALL_GRAPH             = YES
    CALLER_GRAPH           = YES

    需提前安装 graphviz（见步骤一）。

  2. 忽略不需要的代码
    用 /// @cond 和 /// @endcond 包裹无需生成文档的代码：

    1
    2
    3
    4
    /// @cond
    // 内部辅助函数，不对外暴露
    static void helper() {}
    /// @endcond

  3. 集成到 CMake 构建流程
    在 CMakeLists.txt 中添加：

    1
    2
    3
    4
    5
    6
    7
    8
    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 通常优先解析头文件）。