Doxygen入门指南：从注释到自动文档
Doxygen 入门指南：从注释到自动文档
Doxygen 是一款用于生成代码文档的工具，支持 C、C++、Python 等多种语言，尤其适合 C/C++ 项目。本文将介绍如何使用 Doxygen 规范注释并生成 API 文档。
一、安装 Doxygen
1. Windows
- 下载安装包：Doxygen 官网（选择
doxygen-<version>.setup.exe） - 安装时勾选
doxywizard（图形化配置工具，推荐新手使用）
2. Linux
# Ubuntu/Debian
sudo apt-get install doxygen graphviz # graphviz 用于生成图表
# CentOS
sudo yum install doxygen graphviz
3. macOS
brew install doxygen graphviz
二、基本注释规则
Doxygen 通过识别特定格式的注释生成文档，核心是 /\** ... \*/ 风格的注释块，配合标签（@tag）描述代码信息。
1. 函数 / 方法注释
/*** @brief 计算两个整数的和* * 支持正数、负数和零的加法运算，返回结果不会溢出（假设输入在 int 范围内）* * @param a 第一个加数* @param b 第二个加数* @return 两数之和（int 类型）* @note 若输入超出 int 范围，可能导致未定义行为*/
int add(int a, int b) {return a + b;
}
2. 类 / 结构体注释
/*** @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 文件建议添加头部注释，说明文件功能：
/*** @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:doxygen -g Doxyfile # 生成默认配置 -
编辑
Doxyfile关键配置（可选，默认也可生成文档）：PROJECT_NAME = "OL库" # 项目名称 INPUT = ./src # 代码目录 OUTPUT_DIRECTORY = ./docs # 文档输出目录 RECURSIVE = YES # 递归处理子目录 GENERATE_HTML = YES # 生成HTML文档 -
生成文档：
doxygen Doxyfile # 执行配置文件
- 下面是采用我开源的OL库生成的开发文档示例（项目地址：https://github.com/1613661434/OL.git）
五、高级技巧
-
生成调用关系图
在Doxyfile中开启：HAVE_DOT = YES CALL_GRAPH = YES CALLER_GRAPH = YES需提前安装
graphviz（见步骤一）。 -
忽略不需要的代码
用/// @cond和/// @endcond包裹无需生成文档的代码：/// @cond // 内部辅助函数，不对外暴露 static void helper() {} /// @endcond -
集成到 CMake 构建流程
在CMakeLists.txt中添加：find_package(Doxygen) if(DOXYGEN_FOUND)add_custom_target(docsCOMMAND doxygen DoxyfileWORKING_DIRECTORY ${CMAKE_SOURCE_DIR}COMMENT "生成API文档") endif()之后可通过
make docs（Linux）或cmake --build . --target docs生成文档。
六、常见问题
- 注释不生效？
确保注释块以/**开头（不是/*或//），且标签拼写正确（区分大小写）。 - 中文乱码？
在Doxyfile中设置DOXYFILE_ENCODING = UTF-8和OUTPUT_LANGUAGE = Chinese。 - 文档缺少函数？
检查函数是否在.h头文件中声明（Doxygen 通常优先解析头文件）。