Doxygen 是 C++ 项目主流文档生成工具，需安装工具、编写标准注释（如 ///@brief/@param）、生成配置文件（doxygen -g）并运行 doxygen Doxyfile 生成 HTML 等文档，配合小技巧可提升质量。
Doxygen 是 C++ 项目最主流的文档生成工具，它能从源码注释中自动提取结构化文档（HTML、LaTeX、XML 等），无需手写文档框架。关键在于写对注释格式，并配好配置文件。
1. 安装 Doxygen 工具
Windows 用户可直接下载官方安装包（doxygen.nl/download）；macOS 推荐用 Homebrew：brew install doxygen；Linux（如 Ubuntu）执行：sudo apt install doxygen。安装后终端运行 doxygen -v 验证是否成功。
2. 在代码中写标准 Doxygen 注释
Doxygen 不解析普通注释（// 或 /* */），必须使用特定标记开头：
-
///或/**开头的行会被识别为文档块（推荐用///写单行，/** */写多行） - 函数前加注释，用
@param描述参数，@return说明返回值，@brief给简短概述 - 类/结构体前用
@brief和@details区分摘要与详细说明
示例：
立即学习“C++免费学习笔记（深入）”；
/// @brief 计算两个整数的最大公约数 /// @details 使用欧几里得算法递归实现 /// @param a 第一个非负整数 /// @param b 第二个非负整数 /// @return 两数的最大公约数 int gcd(int a, int b);
3. 生成配置文件并运行
在项目根目录执行：doxygen -g Doxyfile，生成默认配置文件。常用修改项包括：
-
PROJECT_NAME：设为你的项目名 -
INPUT：指定源码路径，如src/ include/ -
FILE_PATTERNS：添加*.h *.hpp *.cpp *.cc -
RECURSIVE：设为YES以递归扫描子目录 -
GENERATE_HTML和GENERATE_XML：按需开启
保存后运行：doxygen Doxyfile，输出默认在 html/ 目录，直接打开 index.html 即可浏览。
4. 提升文档质量的小技巧
让生成结果更专业，可以：
- 在头文件顶部加
/** @mainpage 项目说明 */定义首页内容 - 用
@defgroup和@ingroup对功能模块分组 - 用
@code ... @endcode块插入代码片段 - 启用
EXTRACT_ALL = YES可强制文档化未加注释的符号（调试阶段有用） - 配合
DOT_PATH和 Graphviz 生成类图、调用图（需额外安装）
不复杂但容易忽略：每次更新接口后，重新运行 doxygen 就能同步刷新文档，真正实现“代码即文档”。
