doxygen命令必须先加入系统path，否则vs code插件无法生成文档；需安装doxygen并验证版本，再配置doxygen documentation generator插件及doxyfile关键参数。
装完插件不等于能用，doxygen 命令必须先在系统 PATH 里可用，否则所有“一键生成”都会静默失败——这是最常被跳过的一步。
确认 doxygen 命令行工具已安装并可调用
VS Code 插件（如 Doxygen Documentation Generator）只负责写注释模板，真正解析和生成文档靠的是本地 doxygen 可执行文件。没它，插件连预览都做不到。
- macOS：运行
brew install doxygen，再执行doxygen -v确认输出版本号（如1.9.8） - Windows：下载官方安装包（
doxygen-1.9.8-setup.exe），安装时务必勾选Add doxygen to PATH；安装完重启 VS Code 终端，再运行doxygen -v - Linux：执行
sudo apt install doxygen（Ubuntu/Debian），然后验证which doxygen是否返回路径 - VS Code 内置终端中运行
doxygen -g Doxyfile，若提示command not found，说明上一步没走通，别往下试了
安装并配置 Doxygen Documentation Generator 插件
这个插件是目前 VS Code 中最稳定、支持语言最多、且由 Microsoft 官方维护的 Doxygen 注释生成器。第三方同名插件常有参数识别错误或 Python 支持缺失问题。
- 在扩展市场搜索
Doxygen Documentation Generator，认准作者是ms-vscode - 安装后打开设置（
Cmd+,或Ctrl+,），搜索doxygen，重点配三项：doxdocgen.generic.authorName（填你名字）、doxdocgen.generic.dateFormat（建议设为YYYY-MM-DD）、doxdocgen.c.triggerSequence（保持默认/**） - 如果当前文件语言模式不对（右下角显示
Plain Text而非C++或Python），插件会完全不响应——点击右下角语言标识手动切换
函数注释模板生成：快捷键 vs 手动触发
光标必须严格落在函数声明/定义行的正上方空白行，否则插件无法推断参数列表，生成的 @param 字段会为空或错位。
- 推荐方式：把光标放在
int add(int a, int b);这一行的上一行，按Alt+Shift+D（Windows/Linux）或Option+Cmd+D（macOS） - 备用方式：按
Cmd+Shift+P→ 输入Doxygen: Generate Comment→ 回车；若提示No valid symbol found，说明光标位置或语法格式不满足识别条件（比如函数在宏里、或用了 C++20 的 deduced return type） - 注意：插件对模板函数、重载函数、lambda 参数识别有限，此时建议手写
@tparam或用命令面板 + 手动补全
生成 HTML 文档前必须手动改 Doxyfile
插件不生成也不修改 Doxyfile，而默认配置几乎无法直接产出可用文档——尤其 INPUT 路径、PROJECT_NAME 和 RECURSIVE 这三项不改，生成结果就是空目录。
- 在项目根目录运行
doxygen -g生成初始Doxyfile - 用 VS Code 打开它，至少修改三处：
PROJECT_NAME = "MyProject"、INPUT = ./src ./include（按你实际源码路径填）、RECURSIVE = YES - 如果函数在头文件里定义（如 inline 函数），记得把头文件路径也加进
INPUT，否则@param不会被提取 - 运行
doxygen Doxyfile后检查终端输出，出现Searching for include files...且末尾有Generating html...才算成功；若卡在中间或报Warning: ignoring deprecated tag，多数是 Doxyfile 版本不匹配，删掉旧文件重-g一次
最容易被忽略的点：插件生成的注释是否被 doxygen 实际识别，取决于注释风格是否匹配 Doxyfile 中的 EXTRACT_* 设置，以及函数签名是否被完整解析——比如带默认参数的函数，插件可能漏掉 @param 字段，得人工补全。
