Doxygen注释必须紧邻声明上方或同一行右侧，不可置于函数体内或类定义外；正确写法为在成员函数声明前一行用/...*/，或void foo() /。
Doxygen 注释必须紧贴声明，且不能跨函数体插入
很多人把 /** */ 放在函数实现内部、或者在类定义外另起一段写注释，Doxygen 就会完全忽略。它只认「紧邻声明上方」或「同一行右侧」的注释块。
- ✅ 正确：类成员函数声明前一行用
/** ... */，或写成void foo() /** - ❌ 错误：在
public:下方空一行再写注释；或在{}里写注释后指望它生成 API 文档 - ⚠️ 特别注意：模板类/函数的声明若被分行（比如
template<typename t></typename>单独一行），Doxygen 可能无法关联注释——把template行和声明写在同一逻辑块里更稳妥
@param 和 @return 必须与实际签名严格一致
Doxygen 不做语义校验，@param x 写了但函数根本没有叫 x 的参数，它照样生成文档，但读者会困惑。更隐蔽的问题是引用类型、const 限定符、默认参数是否显式标注。
- 参数名必须拼写完全一致，包括下划线、大小写：
@param data_ptr对应int* data_ptr，不是dataptr或DataPtr - 指针/引用要体现：
@param buf [out] uint8_t* const比@param buf更准确，Doxygen 本身不解析类型，但人需要信息 -
@return后建议加类型说明，尤其重载函数多时：@return std::shared_ptr<config> on success, nullptr on failure</config>
用 @brief + @details 拆分摘要与正文，避免大段堆砌
Doxygen 默认只把第一句当摘要（@brief 自动提取），后面全塞进详情区。如果不用显式标记，换行、缩进、空行都无效，会导致 HTML 输出一团乱。
- ✅ 推荐结构：
/** @brief 简短动词开头，20 字内* @details 展开说明用途、典型调用场景、线程安全、生命周期约束等*/ - ⚠️ 常见坑：在
@brief后直接空行，Doxygen 会截断——必须用@details显式开启新段落 - 复杂返回逻辑建议用
@retval而非自然语言描述：@retval true if initialized, false if device not found
结构体/枚举成员必须逐个注释，否则 Doxygen 不生成字段文档
类的 public 成员变量、struct 字段、enum 枚举值，如果不单独加注释，Doxygen 默认只列名字，不带说明。这对 API 文档完整性是硬伤。
立即学习“C++免费学习笔记（深入）”；
- struct 每个字段前加
/// 行尾注释，或独立 <code>/** 块（推荐后者，兼容性更好） - enum 值必须每个都注释：
ENUM_A = 1, /**，漏掉一个，HTML 列表里就少一行说明 - 继承关系要用
@extends（C++ 类）或@ingroup（模块归类），否则生成的类图里看不到父子链接
真正难的不是写全标签，而是让注释和代码变更保持同步。比如重构时改了参数名却忘了更新 @param，或删了默认参数但没删 = nullptr 的注释说明——这类不一致 Doxygen 从不报错，但文档就失效了。
