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 对模板、重载、命名空间等支持良好，但需注意细节：
立即学习“C++免费学习笔记（深入）”；
- 模板类/函数的注释写在 声明处（不是实现），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 文档。不复杂但容易忽略的是：注释位置必须紧贴声明，且不能混用风格 —— 统一用 /// 或 /** */ 效果最稳。
