Doxygen仅解析以///或/开头的文档块注释，普通//或/ /注释被忽略；需符合其标记规范才能生成HTML文档。

Doxygen 能直接从 C++ 源码注释生成 HTML 文档，但前提是注释格式必须被它识别——不是所有 // 或 /* */ 都算“文档注释”，只有以特定标记开头（如 ///、/**）且结构合规的注释才会被提取。

哪些注释会被 Doxygen 解析

Doxygen 默认只处理“文档块”（documented blocks），普通代码注释会被忽略。关键看开头标记和上下文：

• /// 或 ///：用于单行函数/变量声明上方，或跟在声明后（int x; ///）
• /** ... */ 或 /*! ... */：多行块，必须紧贴声明前（中间不能有空行）
• //! 和 //! 也支持，但不如 /// 常用
• 类/函数/枚举前的注释块必须与声明之间**无空行**，否则 Doxygen 视为孤立注释，不绑定

关键配置项：Doxyfile 必设参数

运行 doxygen -g 生成默认配置后，至少要改这几项，否则 HTML 输出可能为空或乱码：

• PROJECT_NAME = "MyLib"：项目名，影响首页标题
• INPUT = ./src ./include：指定含源码和头文件的目录（支持通配符如 ./src/*.h）
• RECURSIVE = YES：是否递归扫描子目录
• EXTRACT_ALL = YES：强制提取所有符号（即使没写注释），方便初期梳理接口
• GENERATE_HTML = YES（默认已开），同时建议开 GENERATE_TREEVIEW = YES 方便导航
• OUTPUT_DIRECTORY = ./docs：输出路径，确保该目录可写

常见错误：生成的 HTML 里看不到函数或类

最常因三类问题导致内容缺失：

• 注释写在声明**之后**且中间有空行，例如：

  class Widget { };
  /// @brief A widget
  class Widget { };

  → Doxygen 不关联
• 用了 // 而非 ///，比如：

  // @param x horizontal position
  void setPos(int x);

  → 不解析
• INPUT 路径写错，或文件扩展名未包含在 FILE_PATTERNS 中（默认含 *.h *.hpp *.cpp *.cc，但若用 .tcc 就要手动加）
• 函数定义在 .cpp 里，但 INPUT 只指定了 ./include，而头文件里没写文档注释

一个最小可用示例

假设有 math_utils.h：

/// @file math_utils.h
/// @brief Basic math utilities for vector operations.
ifndef MATH_UTILS_H
define MATH_UTILS_H
/// @brief Compute squared distance between two 2D points.
/// @param x1 X coordinate of first point
/// @param y1 Y coordinate of first point
/// @param x2 X coordinate of second point
/// @param y2 Y coordinate of second point
/// @return Squared Euclidean distance (no sqrt)
double sqDistance(double x1, double y1, double x2, double y2);
endif // MATH_UTILS_H

配好 Doxyfile 后执行 doxygen，就会在 ./docs/html/index.html 里看到带参数说明的函数页。注意：@file 和 @brief 这类命令必须写在注释块内，且大小写敏感（@param 不是 @PARAM）。

真正卡住人的往往不是语法，而是注释与声明的物理位置关系、路径配置的拼写错误、以及默认 EXTRACT_ALL = NO 导致未注释的类直接消失——先开 EXTRACT_ALL 看全貌，再逐个补文档，比反复猜哪里漏了更省时间。