Doxygen配置需统一INPUT路径、开启RECURSIVE和EXTRACT_ALL、规范注释位置与语法、启用SEARCHENGINE和TREEVIEW提升HTML体验，并在CI中固定工作目录且校验输出。
Doxygen配置文件怎么写才不踩坑
Doxygen本身不难用，难的是第一次配Doxyfile时被一堆开关绕晕。团队协作下最常出问题的是路径、输入范围和输出格式三块。
常见错误现象：doxygen跑完没生成任何HTML，或者只扫了头文件没扫源文件，又或者链接全404——基本都是INPUT、RECURSIVE、EXTRACT_ALL没对齐。
-
INPUT填相对路径时，必须相对于Doxyfile所在目录；建议统一用项目根目录，比如INPUT = ./src ./include - 开启
RECURSIVE = YES，否则子目录里的文件不会被扫描 - 团队代码注释风格不统一？加
EXTRACT_ALL = YES和EXTRACT_STATIC = YES，避免漏掉没写/**的函数 - 如果用C++17以上特性（比如
std::optional），务必设ENABLE_PREPROCESSING = YES，否则模板别名和concept可能解析失败
注释怎么写才能被Doxygen正确识别
不是所有/** */都能被识别成文档块，Doxygen对“位置”和“语法”有硬要求。尤其在类成员函数、重载函数、模板特化这些地方，错一个符号就丢文档。
使用场景：多人维护同一模块，有人习惯在声明处写注释，有人偏爱实现在.cpp里写——Doxygen默认只认声明处的注释。
立即学习“C++免费学习笔记（深入）”；
- 类内函数声明前用
/** ... */或/// ...（注意是三个斜杠） - 避免在函数实现上方写
/** */，除非你开了EXTRACT_LOCAL_METHODS = YES（不推荐，易混乱） - 参数名必须和声明完全一致，
@param buf写成@param buffer会导致参数描述丢失 - 模板类/函数必须在模板声明行上方写注释，而不是在
class X {之前——否则T类型参数不会被识别
HTML输出如何适配团队内部浏览习惯
默认生成的HTML结构太“学术风”，团队日常查API时更想要快速跳转、深色模式、搜索响应快。这些不是靠主题切换能解决的，得动配置。
性能影响：开SEARCHENGINE = YES会多生成search/目录和JS文件，首次加载略慢，但后续搜索极快；关了它，index.html里连搜索框都没有。
- 加
GENERATE_TREEVIEW = YES，左侧导航栏变成可折叠树形，比默认平铺友好得多 - 设
HTML_COLORSTYLE = 1启用深色模式支持（现代浏览器自动识别@media (prefers-color-scheme: dark)） - 禁用
DISABLE_INDEX = YES，否则首页没有全局符号索引，查ConfigLoader得靠Ctrl+F - 如果部署到内网静态服务（比如Nginx），确保
HTML_OUTPUT = html且路径不含空格或中文，否则JS加载失败，搜索功能直接瘫痪
CI流程里怎么稳定触发文档更新
本地能跑通，CI里却生成空白页面，十有八九是工作目录或Git稀疏检出导致INPUT路径失效。团队用GitHub Actions或GitLab CI时，这个坑几乎人人踩过。
兼容性影响：不同CI环境默认Shell不同（bash/zsh/sh），doxygen -g生成的Doxyfile里带bash语法会挂掉。
- CI脚本里显式指定工作目录：
cd $CI_PROJECT_DIR && doxygen Doxyfile，别依赖默认路径 - 把
Doxyfile提交进仓库，禁止用doxygen -g动态生成——CI镜像里没有编辑器，也别指望它帮你补全路径 - 加校验步骤：
test -d html/ && test -s html/index.html，防止静默失败 - 如果文档要推送到Pages分支，记得
git checkout -b gh-pages前先rm -rf *，否则旧HTML残留导致链接错乱
Doxygen真正难的不是语法，是让所有人写的注释、所有人配的路径、所有CI节点的环境，都对齐同一个隐含假设：文档是代码的一等公民，不是发布前补的作业。
