Doxygen注释重在结构化标记而非堆砌文字，需用@param、@return等命令准确标注函数签名与语义；类成员注释必须置于头文件声明行上方，否则无法索引和解析继承关系。
Doxygen 注释不是“写得越多越好”，而是要让 doxygen 能准确提取符号语义、关联关系和调用上下文——关键在结构化标记，不在段落堆砌。
用对 Doxygen 命令标记函数签名与参数
函数文档必须显式声明参数、返回值、异常，否则生成的 HTML 中参数表为空、@return 不出现，且 IDE（如 VS Code + Doxygen Documentation Generator）无法补全提示。
常见错误是只写自然语言描述，漏掉命令标记：
/** * @brief 计算两个整数的最大公约数 * @param a 第一个整数 * @param b 第二个整数 * @return 非负整数，即 gcd(a, b) * @throw std::invalid_argument 当 a 和 b 均为 0 时抛出 */ int gcd(int a, int b);
注意：@brief 后必须换行或加空格再写正文；@param 名称必须与函数声明中完全一致（区分大小写）；@throw 的异常类型应与 noexcept 声明或实际 throw 语句匹配。
立即学习“C++免费学习笔记（深入）”；
类成员注释要绑定到声明行，而非定义行
Doxygen 默认按源码位置解析，把注释写在 .cpp 文件里的函数定义上方，会导致类成员（尤其是 private 成员）不被索引，继承关系断裂。
正确做法是：所有类声明（含 public/protected/private 区块内）的成员注释，必须紧贴其在 .h 文件中的声明行上方：
class Buffer {
public:
/**
* @brief 构造指定容量的缓冲区
* @param capacity 缓冲区字节数，必须 > 0
*/
explicit Buffer(size_t capacity);
private:
char* data_; ///< 堆分配的原始内存指针
sizet capacity; ///< 总容量（字节）
};
其中 /// 是行尾注释语法，适用于简单字段说明；复杂字段（如模板参数、生命周期约束）仍建议用块注释 + @brief。
避免 @file 和 @defgroup 误用导致模块混乱
很多项目在每个 .h 顶部加 @file，结果生成文档时所有文件挤在同一个“Files”页，失去模块划分意义。真正需要的是逻辑分组。
推荐做法：
- 在主头文件（如
core.hpp）顶部用@defgroup core Core Library定义模块 - 在同模块其他头文件顶部用
@ingroup core归属，而非重复@defgroup -
@file仅用于无对应模块的独立工具文件（如build_info.hpp），且需配@brief
若使用 @mainpage，务必放在单独的 mainpage.dox 中，并在 Doxyfile 中通过 INPUT += mainpage.dox 显式引入——否则 doxygen 会忽略它。
配置 Doxyfile 时重点打开这三项
默认配置下，Doxygen 会跳过未显式注释的符号，且不解析模板实例化。要生成完整 API 文档，必须手动开启：
-
EXTRACT_ALL = YES：保证所有声明（即使没加注释）也出现在文档中，作为占位参考 -
EXTRACT_STATIC = YES：导出static成员函数/变量，否则它们不会出现在类页面里 -
TEMPLATE_RELATIONS = YES：启用模板特化关系图（如std::vector指向std::vector基模板）
另外，RECURSIVE = YES 和 INCLUDE_PATH 必须设对，否则 @include 或 @ref 跨目录链接会失败；路径一律用正斜杠（/），Windows 下也别用反斜杠。
最易被忽略的一点：Doxygen 不解析预处理器宏展开后的代码。如果接口大量依赖 MACRO(int foo) 这类包装，必须在宏定义处加注释，或改用 @copydoc 引用原始声明——否则生成的文档里只会显示宏名，没有参数和返回值。
