Doxygen 正确提取类和函数信息需注释位于头文件中、紧贴声明行且结构完整；.cpp 中注释无效，private 成员不显示，每个成员须单独注释于其声明正上方。
Doxygen 能正确提取类和函数信息的前提，是注释位置对、标记准、结构完整——写在 .cpp 里、漏 @param、参数名大小写不一致，都会导致生成文档中字段为空或 IDE 补全失效。
类注释必须紧贴头文件中的声明行
Doxygen 按源码物理位置索引符号，private 成员、构造函数、继承关系等全部依赖头文件（.h）中的声明位置。把注释写在 .cpp 的定义上方，等于没写。
- ✅ 正确：注释块紧贴
class关键字前一行，或类名正上方 - ✅
public/protected/private区块内的每个成员（含函数、变量）都需单独注释，且必须在其声明行正上方 - ❌ 错误：在 .cpp 文件里给
Buffer::Buffer(size_t)写注释——Doxygen 不会关联到头文件中的声明，private成员直接不显示 - ⚠️ 注意：
///行注释可用于简单字段（如size_t capacity_; ///），但复杂语义（如生命周期约束、线程安全要求）仍要用 <code>/** */块注释 +@brief
函数注释必须显式标注 @param 和 @return
仅写自然语言描述（比如“计算最大公约数”）不会让 Doxygen 解析出参数表或返回值类型，HTML 文档里对应字段留空，VS Code 等 IDE 也无法悬停提示。
- ✅
@param名称必须与函数签名中**完全一致**（区分大小写、下划线、const 引用符号等）；例如void push_back(T&& element)→ 必须写@param element，不能写@param e或@param Element - ✅
@return要说明值的语义，不只是类型；比如@return 非负整数，即 gcd(a, b)比@return int有用得多 - ✅ 若函数可能抛异常，必须写
@throw，且异常类型要与实际throw语句或noexcept声明匹配（如@throw std::invalid_argument） - ⚠️ 注意：
@brief后必须换行或加空格再写正文，否则 Doxygen 可能截断；多行详细描述与@brief之间要空一行
模板类/函数需用 @tparam 显式说明类型参数
Doxygen 不会自动推导模板参数约束，不写 @tparam 就无法生成模板参数文档，IDE 也无法补全泛型上下文。
立即学习“C++免费学习笔记（深入）”；
- ✅ 模板类示例：
template<typename T> class DynamicArray→ 注释中必须有@tparam T 元素类型（需支持移动构造） - ✅ 模板函数同理：
template<typename T> void swap(T&, T&)→ 对应@tparam T 类型必须可拷贝赋值 - ✅ 若模板有 SFINAE 或 concept 约束（如 C++20
std::sortable），应在@tparam或@note中说明，否则文档无法反映真实使用边界 - ⚠️ 注意：不要用
@param T替代@tparam T——Doxygen 会把它当成普通参数，生成错误的参数表
别忽略注释语法细节和配置联动
即使内容写对了，格式错一个字符或配置没开关键选项，也会让整个注释失效。
- ✅ 注释风格优先选
/** */（多行）或///（单行），避免用/*! */——部分旧版 Doxygen 对它支持不稳定 - ✅ 配置文件
Doxyfile中必须设EXTRACT_ALL = YES（否则未注释的符号不索引）、RECURSIVE = YES（否则子目录不扫描） - ✅ 行尾注释用
///（两个斜杠加尖括号），不是 <code>//或///；例如double x_; /// - ⚠️ 注意：Doxygen 默认只解析以
/**、///、//!开头的注释；普通/* */或//完全被忽略
最容易被跳过的其实是参数名一致性、@tparam 和 @param 的严格区分，以及头文件声明与注释的物理绑定——这些不是“写了就行”，而是“写错就等于没写”。
