17370845950

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 不解析普通注释，只识别以 /**、/// 或 /*! 开头的特殊注释块。推荐统一用 ///（简洁）或 /**（支持多行+富文本）。

• 类/结构体：在 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，把文档质量纳入静态检查环节

不复杂但容易忽略：每次重构接口时，顺手更新对应注释——这是维持文档可信度的核心习惯。