Doxygen注释需覆盖接口契约等四要素才能生成合格API手册；必需标签包括@param[in/out]、@return（含错误码）、@throw、@pre/@post、@note/@warning；C++特性如模板重载须单独注释；doxygen.conf需启用EXTRACT_ALL、EXTRACT_STATIC等配置。
Doxygen 注释本身不生成“手册”，它只生成结构化文档数据；能否产出合格的 API 开发手册，取决于注释是否覆盖接口契约、参数边界、错误行为和调用约束——而多数 C++ 项目只写 @brief，这远远不够。
哪些 Doxygen 标签是 API 手册必需的
仅靠 @brief 或 @param 无法支撑开发者理解如何安全调用函数。真实协作中必须补全以下标签：
-
@param [in/out/inout]：明确标注参数流向，尤其指针/引用参数必须说明是否可为nullptr、是否被修改、是否需调用方释放 -
@return：不能只写“返回结果”，要写清成功值范围（如非负整数）、错误码定义（如-EINVAL）、异常抛出条件（如std::invalid_argument） -
@throw或@exception：C++ 中若函数可能抛异常，必须列出所有可能类型及触发场景（例如“当path不存在且create_if_missing == false时抛std::filesystem::filesystem_error”） -
@pre/@post：对有状态操作（如类成员函数）必须声明前置条件（如“要求is_open() == true”）和后置效果（如“保证内部缓冲区清空，bytes_written()返回实际写入字节数”） -
@note和@warning：用于标记线程安全性（如“非线程安全，需外部同步”）、生命周期约束（如“返回的const char*指向内部缓冲区，仅在本对象生命周期内有效”）
C++ 特有结构的注释陷阱
模板、重载、移动语义、SFINAE 等特性会让 Doxygen 解析失真或遗漏关键信息：
- 函数模板必须在每个特化或约束分支上单独注释，
template上的@brief不会自动继承到foo页面 - 重载函数之间不能共用同一段注释——Doxygen 会把所有同名函数的注释拼在一起，导致参数说明错位；每个重载都应有独立完整的
@param+@return - 移动构造函数/赋值运算符必须显式标注“接管资源所有权”，并说明源对象进入何种有效但未指定状态（如“
other处于可析构、可赋值状态，但其data_成员为nullptr”） - 使用
std::enable_if_t或 Concepts 的约束函数，应在@tparam中解释 SFINAE 条件的实际含义（例如“仅当T支持operator 时启用”）
doxygen.conf 关键配置项影响输出质量
默认配置会隐藏大量有用信息，API 手册级输出需手动开启：
