<p>Doxygen 正确生成 API 文档需满足三要素：规范注释（用 /* / 或 /// 紧邻声明，配合 @param 等标记）、合理配置（如 INPUT、RECURSIVE、EXTRACT_ALL）及适配现代 C++ 特性（启用宏展开、手动处理 concept 等）。</p>
Doxygen 能从 C++ 源码注释生成 API 文档，但前提是注释格式正确、配置合理，且项目结构不干扰解析 —— 否则生成的文档会漏函数、错分类，甚至根本不出 html 或 xml 输出。
怎么写注释才能被 Doxygen 识别
Doxygen 不解析普通双斜杠注释，只认特定风格的块注释。最稳妥的是用 /** */ 或 /// 开头，并在紧邻声明前（中间不能插空行）。
-
/**块内用@param、@return、@brief等标记，注意冒号后要空格，比如@param x input value - 类声明前的注释会被绑定到该类；成员函数前的注释绑定到该函数，哪怕它在
private:区域里 - 避免在注释里写未转义的
或 <code>>，否则 Doxygen 可能误解析为 HTML 标签；用<和>替代 - 如果函数重载多，每个都要单独注释，Doxygen 不会“自动合并”或“继承”上一个的说明
doxygen -g 生成的默认配置为什么常失效
doxygen -g 生成的是通用模板，对 C++ 项目往往缺关键开关，导致找不到源文件或忽略模板/内联函数。
- 必须手动改
INPUT：填入实际头文件和源文件路径，支持通配符，例如INPUT = ./include ./src - 开启
RECURSIVE = YES，否则子目录里的文件不会被扫描 - C++ 模板类/函数默认不生成文档，需设
EXTRACT_ALL = YES或EXTRACT_PRIVATE = YES（视需求），否则std::vector<T>这种实例化类型可能空白 - 若用
auto推导返回类型，建议同时开OPTIMIZE_OUTPUT_FOR_C = NO和EXTRACT_ANON_NSPACES = YES，否则返回类型可能显示为auto而非真实类型
生成 HTML 时函数列表为空或链接 404
常见原因是符号解析失败，不是注释没写，而是 Doxygen 没“看懂”声明结构。
立即学习“C++免费学习笔记（深入）”；
- 确保头文件中类定义完整，不要用前置声明代替定义（如
class Foo;后直接注释，Doxygen 无法关联） - 模板特化（如
template <> class Foo<int>）需要独立注释，且位置必须在特化定义之前 - 若使用模块化构建（如 CMake +
target_include_directories），Doxygen 不读构建系统配置，得手动在INCLUDE_PATH中补全依赖头文件路径 - 检查日志输出：运行
doxygen -u可更新配置，加-d parse能看到它是否成功识别了某个函数声明；错误通常以warning: unable to resolve reference to开头
如何让 Doxygen 正确处理现代 C++ 特性
C++17/20 的 constexpr if、concept、requires 子句容易让 Doxygen 解析器卡住或跳过整个函数。
- 对于
concept，在概念定义前加注释即可，但调用处的约束子句（如void foo() requires C<T>）目前 Doxygen 仍显示为原始语法，无法自动展开约束条件 -
constexpr if块内的代码不影响文档生成，但若分支里有未声明的类型别名，可能导致解析中断 —— 建议把类型别名提至函数外或加typedef注释 - 使用
ALIASES = "concept=\xrefitem concept \"Concept\" \"Concepts\""可自定义标记，在注释中写@concept MyConstraint手动归类 - 启用
MACRO_EXPANSION = YES和EXPAND_MACROS = YES，否则带宏的声明（如MY_API void func();）可能被跳过
最易被忽略的一点：Doxygen 不做语义分析，它只做词法+简单语法解析。所以即使代码能编译通过，只要声明格式稍偏（比如换行位置不对、缺少分号、嵌套注释），就可能静默丢弃该条目 —— 验证方式不是看有没有报错，而是打开生成的 index.html，搜索你确认写了注释的函数名，看是否出现。
