17370845950

Doxygen是C++主流文档工具，通过///或/**/注释提取API文档；需正确注释位置、配置Doxyfile、支持模板/重载解析，并集成到CMake/CI流程中实现自动化。

Doxygen 是 C++ 项目最主流的文档生成工具，它能从源码注释中自动提取结构化文档（HTML、LaTeX、Markdown 等格式），关键在于写对注释格式，再配好配置文件。

注释怎么写才被 Doxygen 识别

Doxygen 主要识别以 /** 或 /// 开头的注释块。普通 // 或 /* */ 不参与文档生成。

• 类/结构体：在声明前用 /** ... */ 或 /// 描述整体功能，支持 @brief、@details 分段
• 成员函数：在函数声明上方注释，用 @param 标参数，@return 写返回值，@throw 说明异常
• 变量/枚举值：直接在定义前加单行 /// 注释即可，如 /// 最大连接数
• 特殊命令：常用 @see 引用其他符号，@note 加备注，@warning 标警告，支持简单 Markdown（如 **粗体**）

快速生成并运行 Doxygen 配置

不用手写全部配置，用交互式命令初始化：

• 终端进入项目根目录，运行 doxygen -g Doxyfile —— 生成默认配置文件
• 编辑 Doxyfile，重点改几项：
  PROJECT_NAME = "MyCppLib"
INPUT = ./src ./include（指定含注释的源码路径）
  RECURSIVE = YES（递归扫描子目录）
  GENERATE_HTML = YES（生成 HTML 文档）
  GENERATE_LATEX = NO（不需要 PDF 可关掉）
• 保存后执行 doxygen Doxyfile，几秒后会在 html/ 目录生成完整文档

让 C++ 特性被正确解析

Doxygen 对模板、重载、命名空间等支持良好，但需注意细节：

• 模板类/函数的注释写在 声明处（不是实现），Doxygen 能自动关联实例化类型
• 重载函数各自独立注释，Doxygen 会为每个签名生成单独文档页
• 使用 @fn 手动标记函数名（当声明和实现分离时，避免解析错位）
• 开启 EXTRACT_ALL = YES 可强制文档化所有符号（包括未注释的），适合初期梳理接口
• 添加 ENABLE_PREPROCESSING = YES 和 MACRO_EXPANSION = YES 支持宏定义中的文档提取（如 MY_API void func();）

集成到开发流程中（推荐做法）

避免文档过期，把 Doxygen 当成构建环节的一部分：

• CMake 项目中加入 find_package(Doxygen)，用 add_custom_target(doc ...) 定义 make doc 命令
• CI 流程（如 GitHub Actions）中增加步骤：每次 push 后自动生成文档并部署到 Pages
• 编辑器插件辅助：VS Code 安装 “Doxygen Documentation Generator”，输入 /// 自动补全注释骨架
• 定期用 doxygen -w html header.html footer.html stylesheet.css 自定义页面样式，保持品牌一致

基本上就这些。写清楚注释 + 一次配置 + 加入流程，就能让 C++ 项目自带可搜索、带跳转、跨平台的 API 文档。不复杂但容易忽略的是：注释位置必须紧贴声明，且不能混用风格 —— 统一用 /// 或 /** */ 效果最稳。