C++项目Doxygen注释编写与自动生成指南

Doxygen注释重在结构化标记而非堆砌文字，需用@param、@return等命令准确标注函数签名与语义；类成员注释必须置于头文件声明行上方，否则无法索引和解析继承关系。

Doxygen 注释不是“写得越多越好”，而是要让 doxygen 能准确提取符号语义、关联关系和调用上下文——关键在结构化标记，不在段落堆砌。

用对 Doxygen 命令标记函数签名与参数

函数文档必须显式声明参数、返回值、异常，否则生成的 HTML 中参数表为空、@return 不出现，且 IDE（如 VS Code + Doxygen Documentation Generator）无法补全提示。

常见错误是只写自然语言描述，漏掉命令标记：

/**
 * @brief 计算两个整数的最大公约数
 * @param a 第一个整数
 * @param b 第二个整数
 * @return 非负整数，即 gcd(a, b)
 * @throw std::invalid_argument 当 a 和 b 均为 0 时抛出
 */
int gcd(int a, int b);

注意：@brief 后必须换行或加空格再写正文；@param 名称必须与函数声明中完全一致（区分大小写）；@throw 的异常类型应与 noexcept 声明或实际 throw 语句匹配。

类成员注释要绑定到声明行，而非定义行

Doxygen 默认按源码位置解析，把注释写在 .cpp 文件里的函数定义上方，会导致类成员（尤其是 private 成员）不被索引，继承关系断裂。

正确做法是：所有类声明（含 public/protected/private 区块内）的成员注释，必须紧贴其在 .h 文件中的声明行上方：

class Buffer {
public:
    /**
     * @brief 构造指定容量的缓冲区
     * @param capacity 缓冲区字节数，必须 > 0
     */
    explicit Buffer(size_t capacity);
private:
char* data_;      ///< 堆分配的原始内存指针
sizet capacity; ///< 总容量（字节）
};

其中 ///< 是行尾注释语法，适用于简单字段说明；复杂字段（如模板参数、生命周期约束）仍建议用块注释 + @brief。

避免 @file 和 @defgroup 误用导致模块混乱

很多项目在每个 .h 顶部加 @file，结果生成文档时所有文件挤在同一个“Files”页，失去模块划分意义。真正需要的是逻辑分组。

推荐做法：

• 在主头文件（如 core.hpp）顶部用 @defgroup core Core Library 定义模块
• 在同模块其他头文件顶部用 @ingroup core 归属，而非重复 @defgroup
• @file 仅用于无对应模块的独立工具文件（如 build_info.hpp），且需配 @brief

若使用 @mainpage，务必放在单独的 mainpage.dox 中，并在 Doxyfile 中通过 INPUT += mainpage.dox 显式引入——否则 doxygen 会忽略它。

配置 Doxyfile 时重点打开这三项

默认配置下，Doxygen 会跳过未显式注释的符号，且不解析模板实例化。要生成完整 API 文档，必须手动开启：

• EXTRACT_ALL = YES：保证所有声明（即使没加注释）也出现在文档中，作为占位参考
• EXTRACT_STATIC = YES：导出 static 成员函数/变量，否则它们不会出现在类页面里
• TEMPLATE_RELATIONS = YES：启用模板特化关系图（如 std::vector 指向 std::vector 基模板）

另外，RECURSIVE = YES 和 INCLUDE_PATH 必须设对，否则 @include 或 @ref 跨目录链接会失败；路径一律用正斜杠（/），Windows 下也别用反斜杠。

最易被忽略的一点：Doxygen 不解析预处理器宏展开后的代码。如果接口大量依赖 MACRO(int foo) 这类包装，必须在宏定义处加注释，或改用 @copydoc 引用原始声明——否则生成的文档里只会显示宏名，没有参数和返回值。