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 手册级输出需手动开启：
立即学习“C++免费学习笔记（深入）”；
-
EXTRACT_ALL = YES：否则私有成员、未注释函数不会出现在文档中，但注意：这会让未注释代码暴露——建议配合WARN_IF_UNDOCUMENTED = YES强制补全 -
EXTRACT_STATIC = YES：静态函数/变量常含关键工具逻辑（如内存池分配器），不开启则直接丢失 -
OPTIMIZE_OUTPUT_FOR_C = NO：C++ 项目必须关掉，否则类继承关系、const限定符、引用符号会被简化掉 -
GENERATE_TREEVIEW = YES：提供左侧导航树，方便浏览命名空间/类层级，对大型 API 手册是刚需 -
EXAMPLE_PATH = ./examples：配合@include或@dontinclude引入真实可编译示例，比虚构代码更有说服力
真正难的不是写满 Doxygen 标签，而是让每条注释回答一个具体问题：“调用者需要知道什么才能不 crash、不泄露、不竞态？” 这要求注释者以使用者视角逐行推演——比如看到 std::unique_ptr 参数，就得立刻问：这个引用是否延长了 unique_ptr 生命周期？是否允许传入临时对象？这些细节，@param 后面一句话说不清，就得多加 @warning。
