doxygen命令未加入系统path是插件失效主因；需先通过brew/apt/安装包确保终端可运行doxygen -v，再配置vs code插件、语言模式、光标位置及注释格式。

装了插件却按 Alt+Shift+D 没反应？不是插件坏了，是 doxygen 命令根本没进系统 PATH——这是 90% 用户卡住的第一步。

doxygen 命令必须先在终端里能跑通

插件本身不带解析能力，它只负责把光标位置的函数签名“喂”给本地 doxygen 可执行文件，再把返回的参数、类型、返回值填进注释模板。没这个二进制，所有生成动作都静默失败。

• macOS：运行 brew install doxygen，然后在 VS Code 内置终端输 doxygen -v，看到类似 1.9.8 才算成功
• Windows：下官方安装包（如 doxygen-1.9.8-setup.exe），安装时**必须勾选 “Add doxygen to PATH”**，装完重启 VS Code 终端再验
• Linux（Ubuntu/Debian）：用 sudo apt install doxygen，再跑 which doxygen 看是否返回路径，比如 /usr/bin/doxygen
• 如果 doxygen -g Doxyfile 报 command not found，别往下配插件了，先解决这一步

Doxygen Documentation Generator 插件配置要点

认准作者是 ms-vscode 的官方插件，别装错第三方同名包。装完后重点调三项：

Document to PDF

通过PDFAPIHub云API将office文档（DOCX、DOC、PPT、PPTX、XLS、XLSX、CSV、TXT、ODT、RTF）转换为PDF，文档上传至pdfapihub.com完成转换。

下载

• doxdocgen.generic.authorName：填你名字或团队 ID，后续每条注释都会带上
• doxdocgen.generic.dateFormat：建议设成 YYYY-MM-DD，避免日期格式混乱
• doxdocgen.c.triggerSequence：保持默认 /**，别乱改成 /// 或其他，否则触发失效
• 右下角语言模式必须是 C、C++ 或 Python，显示 Plain Text 或 Unknown 时插件完全不工作——点它手动切过去

光标位置决定能不能生成 @param

插件靠语法上下文推断参数，不是靠猜。光标必须严格落在函数声明/定义行的正上方空白行，例如：

/**

• 光标在函数体内、注释行中间、空行偏移一格，都会导致 @param 字段为空或错位
• C 函数如 int foo(char *buf, size_t len) 能识别出两个参数名，但不会自动补类型说明（那是 Document This 插件干的，但它不支持 C）
• 快捷键 Alt+Shift+D（Win/Linux）或 Option+Cmd+D（macOS）只是快捷方式，本质和输入 /** + 回车一样；后者更稳定，推荐优先用

生成的注释格式容易踩坑

默认输出是紧凑型 /** @brief ... @param a ... */，没换行、没缩进，手写后续内容很难对齐，也影响 doxygen 解析效果。

• 想改成多行风格（如每行一个 @param），得改 doxdocgen.c.commentPrefix 为 " * "，并确认 doxdocgen.c.firstLine 是 "/**"、doxdocgen.c.lastLine 是 " */"
• @brief 后面必须跟空格再写描述，写成 @brief\ 或 @brief\n 都会被 doxygen 忽略
• 如果生成后发现 @returns 缺失，检查函数是不是 void 类型——插件默认不为 void 函数加该字段

最常被忽略的其实是语言模式切换和 doxygen 的 PATH 验证，这两步没走稳，后面所有配置都是白忙。