doxygen仅解析以///或/开头的文档块注释，普通//或/ /注释被忽略；需符合其标记规范才能生成html文档。
Doxygen 能直接从 C++ 源码注释生成 HTML 文档，但前提是注释格式必须被它识别——不是所有 // 或 /* */ 都算“文档注释”，只有以特定标记开头（如 ///、/**）且结构合规的注释才会被提取。
哪些注释会被 Doxygen 解析
Doxygen 默认只处理“文档块”（documented blocks），普通代码注释会被忽略。关键看开头标记和上下文：
-
///或///：用于单行函数/变量声明上方，或跟在声明后（<code>int x; ///） -
/** ... */或/*! ... */：多行块，必须紧贴声明前（中间不能有空行） -
//!和//! 也支持，但不如 <code>///常用 - 类/函数/枚举前的注释块必须与声明之间**无空行**，否则 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. <h1>ifndef MATH_UTILS_H</h1><h1>define MATH_UTILS_H</h1><p>/// @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);</p><h1>endif // MATH_UTILS_H</h1>
配好 Doxyfile 后执行 doxygen，就会在 ./docs/html/index.html 里看到带参数说明的函数页。注意：@file 和 @brief 这类命令必须写在注释块内，且大小写敏感（@param 不是 @PARAM）。
真正卡住人的往往不是语法，而是注释与声明的物理位置关系、路径配置的拼写错误、以及默认 EXTRACT_ALL = NO 导致未注释的类直接消失——先开 EXTRACT_ALL 看全貌，再逐个补文档，比反复猜哪里漏了更省时间。
