如何为c++项目创建一个符合规范的Doxyfile？ (Doxygen文档生成)_技术教程

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 显示）。容易被忽略的是跨模块引用问题：

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