Doxygen注释必须位于头文件中声明正上方且不被预处理器隔断，配置需设EXTRACT_ALL=YES和OPTIMIZE_OUTPUT_FOR_C=NO；否则函数无描述、C++特性不解析。
Doxygen 注释必须紧贴声明，且不能被预处理器隔断
Doxygen 不解析被 #ifdef 包裹的注释块，也不识别定义在实现文件（.cpp）中、但声明在头文件里的函数注释。常见错误是把完整注释写在 .cpp 里，结果生成文档时函数“没描述”或参数全标为 unknown。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 所有公开接口（类、函数、枚举、常量）的 Doxygen 注释必须放在
.h或.hpp文件中，且紧邻其声明上方（中间不能有空行或宏） - 避免在注释前加
#ifdef API_EXPORT等条件编译；如需条件导出，用\if/\endifDoxygen 指令替代 - 成员函数若在类内定义（inline），注释直接写在函数声明前；若在类外定义，注释仍要放在类内声明处，而非
.cpp中的定义处
用 @param、@return、@brief 而不是 /// 自动推导
Doxygen 支持简写风格（如 /// 放在参数后），但实际项目中极易漏写、顺序错位或类型不匹配，导致生成的 HTML 文档中参数表为空或字段错乱。尤其当函数重载多、参数名相似（如 <code>id 和 id_str）时，自动推导完全不可靠。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 统一使用显式命令：每个函数前用
/**开始，@brief描述一句话用途，@param [name]逐个说明参数含义，@return明确返回值语义（不要只写 “true on success”） - 对指针/引用参数，必须注明是否可为
nullptr或是否接管所有权，例如：@param data pointer to owned buffer, may be null - 模板参数用
@tparam单独说明，别指望 Doxygen 自动从template<typename t></typename>提取约束
结构体/类成员必须用 @var 或字段级 @brief 显式注释
Doxygen 默认不会为 struct 的 public 成员生成字段说明——即使你写了 /// 这样的行尾注释，它也常被忽略或归入上一行函数的描述里。结果就是结构体文档里只有空荡荡的成员列表，没有类型、用途、取值范围等关键信息。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 对每个 public 成员变量，在其声明**正上方**单独写一行
/**<code>@brief描述 */，Doxygen 才会将其识别为字段文档 - 更稳妥的方式是用
@var块（适合复杂说明）：/**<br> * @var id<br> * @brief Unique numeric identifier. Must be > 0.<br> */<br>int id;
- 私有成员无需注释（除非暴露给文档读者），但若用了
@private分组，需确保分组标记清晰，否则 Doxygen 可能误将私有成员混入 public 列表
配置文件 Doxyfile 必须启用 EXTRACT_ALL = YES 和 OPTIMIZE_OUTPUT_FOR_C = NO
C++ 项目若沿用 C 语言默认配置，Doxygen 会禁用命名空间、模板、运算符重载等特性的解析，导致类方法消失、模板类显示为 template<...></...> 占位符、operator== 完全不出现。
实操建议：
立即学习“C++免费学习笔记（深入）”；
- 初始化配置时用
doxygen -g生成默认Doxyfile，然后手动修改两处关键项：EXTRACT_ALL = YES（否则只提取带注释的符号）OPTIMIZE_OUTPUT_FOR_C = NO（否则禁用 C++ 特性） - 补充必要路径：
INPUT = ./include（指向头文件根目录）、RECURSIVE = YES（递归扫描子目录） - 若使用现代 C++（如 concepts、requires），需确认 Doxygen 版本 ≥ 1.9.4，旧版本会直接跳过整块模板声明
真正卡住人的往往不是语法怎么写，而是注释位置和配置开关这两个点没对齐——一个在头文件里写得再规范，EXTRACT_ALL = NO 就等于没写；反过来，配置全开但注释飘在 .cpp 里，照样白忙活。
