Doxyfile 是 doxygen -g 生成的模板配置文件，不应手写全量；必须修改 PROJECT_NAME、INPUT 等基础项，并启用 ENABLE_PREPROCESSING、EXTRACT_PRIVATE 等关键开关以支持 C++ 特性与符号可见性。
Doxyfile 是什么，为什么不能手写全量配置
Doxyfile 不是必须从零手写的配置文件，而是 doxygen -g 生成的模板。手动拼凑所有选项极易遗漏关键开关（比如 EXTRACT_ALL 关闭时私有成员默认不文档化），导致生成内容为空或不符合预期。官方推荐流程永远是先生成再按需修改。
用 doxygen -g 生成基础 Doxyfile 并设置项目元信息
在项目根目录执行：
doxygen -g Doxyfile会生成一个完整但注释掉大部分选项的配置文件。接下来必须修改以下几项，否则文档首页无标识、路径解析错误或无法识别 C++17 特性：
-
PROJECT_NAME = "MyCppLib"—— 必须填，空值会导致首页标题异常 -
PROJECT_NUMBER = "1.2.0"—— 建议填，影响版本页展示 -
INPUT = ./src ./include—— 显式列出头文件与实现路径，不要依赖递归（RECURSIVE = YES有性能开销且易误扫构建目录） -
FILE_PATTERNS = *.h *.hpp *.cpp *.cc *.cxx—— 明确扩展名，避免漏掉.hpp或.cc -
EXTENSION_MAPPING = "hpp=C++" "hxx=C++"—— 确保 Doxygen 正确解析现代 C++ 头文件语法
启用 C++ 特性支持与符号可见性控制
默认 Doxyfile 对模板、constexpr、concept、模块（C++20）等支持不足，且会跳过 private 成员。常见错误是只改了 EXTRACT_PRIVATE = YES 却忘了同步打开 EXTRACT_STATIC = YES（否则静态成员不出现）和 EXTRACT_LOCAL_METHODS = YES（否则 lambda 内部函数丢失）：
-
EXTRACT_ALL = NO—— 生产环境建议设为NO，靠EXTRACT_PRIVATE/EXTRACT_STATIC精细控制 -
ENABLE_PREPROCESSING = YES—— 必须开启，否则宏定义、#ifdef区块无法正确展开 -
MACRO_EXPANSION = YES和EXPAND_ONLY_PREDEF = YES—— 配合使用，避免展开全部宏导致文档臃肿 -
PREDEFINED = "DOXYGEN_SHOULD_SKIP_THIS" "Q_DECL_EXPORT="—— 把构建系统中干扰解析的宏显式“清空”，例如 Qt 的导出宏
输出格式、搜索与跨引用的关键开关
只生成 HTML 是最常见需求，但若关闭 GENERATE_TREEVIEW = YES，类继承图将不可折叠；若未设 SEARCHENGINE = YES，网页端搜索框实际不可用（即使 UI 显示）。容易被忽略的是跨模块引用问题：
立即学习“C++免费学习笔记（深入）”；
-
GENERATE_HTML = YES和HTML_OUTPUT = html_doc—— 输出路径别用docs/这类通用名，防止和 CI 脚本冲突 -
GENERATE_LATEX = NO—— 关闭 LaTeX 可显著加快生成速度，除非真要 PDF -
USE_MDFILE_AS_MAINPAGE = README.md—— 若项目有README.md，这行能让它成为首页，比手写mainpage.md更省事 -
ALIASES = "rst=\xrefitem rst "RST" "RST Rules""—— 如需自定义标签（如标记线程安全），用ALIASES而非硬编码xrefitem
复杂点在于：Doxygen 对模板特化、ADL、SFINAE 的解析仍有限，即使配置全开，部分重载或约束失败的函数也可能不显示。这时候得靠 @cond/@endcond 手动包裹，或在代码中加 /// @brief ... 强制暴露。
