doxygen 是 c++ 项目最主流的文档生成工具，需正确编写注释、配置 doxyfile 并同步更新。1. 安装后运行 doxygen -g 生成配置，doxygen 执行构建；2. 使用 /// 或 /** 注释，配合 @brief、@param 等标签；3. 配置 project_name、input、extract_all 等关键项；4. 将 doxyfile 纳入版本控制，集成到 ci 和开发流程中。
Doxygen 是 C++ 项目最主流的文档生成工具，它能从源码注释中自动提取结构化文档（HTML、PDF、XML 等），关键在于写对注释格式、配好配置、保持代码与文档同步。
1. 安装与基础配置
在 Ubuntu/Debian 上执行 sudo apt install doxygen doxygen-latex；macOS 用户可用 brew install doxygen；Windows 推荐下载官方安装包。安装后进入项目根目录，运行：
-
doxygen -g Doxyfile：生成默认配置文件 -
doxygen Doxyfile：按配置生成文档（输出在html/和latex/目录）
建议将 Doxyfile 提交到版本库，并在 CI 中加入 doxygen 步骤，确保每次 PR 都能检查文档完整性。
2. 注释规范：让 Doxygen “看得懂”
Doxygen 不解析普通注释，只识别以 /**、/// 或 /*! 开头的特殊注释块。推荐统一用 ///（简洁）或 /**（支持多行+富文本）。
立即学习“C++免费学习笔记（深入）”；
- 类/结构体：在
class或struct关键字前写完整说明，可用@brief分离简述和详述 - 函数：在声明前注释，用
@param描述每个参数，@return说明返回值，@throw标明异常 - 成员变量：简单说明用途即可，如
/// 毫秒级时间戳，自 Unix 纪元起
示例：
/// @brief 计算两点间欧氏距离 /// @param p1 第一个点（x, y） /// @param p2 第二个点（x, y） /// @return 距离值，非负浮点数 double euclidean_distance(const Point& p1, const Point& p2);
3. 配置文件关键项调优
打开 Doxyfile，重点修改以下字段（大小写敏感）：
-
PROJECT_NAME = "MyCppLib"：项目名，显示在首页标题 -
PROJECT_NUMBER = "v1.2.0"：版本号，建议与 git tag 同步 -
INPUT = ./src ./include：指定源码路径（支持通配符，如./src/*.h *.cpp） -
RECURSIVE = YES：递归扫描子目录 -
EXTRACT_ALL = NO：设为NO可避免未注释符号出现在文档中（更严谨） -
GENERATE_HTML = YES和GENERATE_LATEX = NO：按需开关输出格式 -
QUIET = YES：减少构建日志干扰 CI 输出
4. 集成进开发流程
文档不是“一次性任务”，而是代码的一部分：
- 在
.gitignore中排除html/、latex/、xml/等生成目录，只保留Doxyfile - 在
Makefile或CMakeLists.txt中添加docs目标，例如：make docs执行doxygen Doxyfile - PR 模板中加入检查项：“新增/修改的公共接口是否已补充 Doxygen 注释？”
- 配合 clang-format 和 cpplint，把文档质量纳入静态检查环节
不复杂但容易忽略：每次重构接口时，顺手更新对应注释——这是维持文档可信度的核心习惯。
