必须选对工具链并严格匹配语言模式：c/c++用doxygen且插件语言设为c/cpp，typescript用typedoc需tsconfig开启declaration，python用pdoc须在包根目录激活虚拟环境运行，q#用xml注释脚本；光标须紧贴声明行正上方，状态栏显示对应语言模式，否则上下文识别失败。

VSCode 项目文档自动生成不是“装个插件就完事”，关键在于选对工具链、配对语言特性、避开默认配置的坑。C/C++ 用 Doxygen，TypeScript 用 TypeDoc，Python 用 pdoc，Q# 用 XML 注释提取脚本——混用或强套会导致注释不识别、链接失效、字段丢失。

Doxygen Documentation Generator 插件生成注释模板时没反应

这不是插件坏了，而是上下文识别失败或语言模式没对上。

• 光标必须严格停在函数/类声明行的正上方空白行，不能在花括号里、不能在注释行、不能在宏定义后
• 右下角状态栏必须显示 Cpp 或 C，不是 Plain Text；按 Cmd+K M（macOS）或 Ctrl+K M（Windows/Linux）手动切一次语言模式
• Doxygen: Language 设置必须和当前文件一致：C 文件设为 c，C++ 文件设为 cpp，大小写敏感
• 快捷键冲突常见于 macOS 上的 Option+Cmd+D 被系统快捷键占用，建议改用命令面板：Cmd+Shift+P → 输入 Doxygen: Generate Comment

pdoc 生成 Python 文档时页面空白或报错 ModuleNotFoundError

pdoc 不扫描子目录，也不自动导入未安装的包，路径和环境错一点就直接失败。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• 确保终端当前工作目录是含 __init__.py 的包根目录，不是 src/ 或 lib/ 子目录
• 运行前激活对应虚拟环境，pdoc 默认走系统 Python，不是你项目用的解释器
• 模块名必须可 import：pdoc mypackage 要求能成功执行 import mypackage，否则报 ModuleNotFoundError
• 避免用相对路径如 pdoc ./mypackage，pdoc 只认模块名，不认文件路径；要指定路径请用 --output-directory + 模块名组合

Markdown 目录生成后中文标题点不动

VSCode 内置预览和插件生成的锚点 ID 规则不一致，不是 bug，是配置错位。

• 打开设置搜 markdown.extension.toc.slugifyMode，把值从 github 改成 vscode
• updateOnSave 只刷新已有目录块，首次必须手动运行 Markdown: Create Table of Contents
• 删掉旧目录后，updateOnSave 不会自动重建，得再手动触发一次命令
• 确认文件语言模式是 Markdown（右下角显示），不是 Markdown (plain) 或其他变体

TypeDoc 生成 API 文档时类型丢失或页面空

TypeDoc 依赖 TypeScript 编译器解析 AST，tsconfig.json 配置不对，它就看不到类型信息。

• typedoc.json 中的 entryPoints 必须指向已编译过的 .ts 文件，不是 .d.ts 或构建产物
• tsconfig.json 里至少要有 "compilerOptions": { "declaration": true }，否则 TypeDoc 无法提取接口定义
• 如果项目用了路径别名（paths），需在 typedoc.json 中加 "tsconfig": "./tsconfig.json" 显式引用
• 注释必须用 JSDoc 格式，/** */ 块内不能有空行，@param 和 @returns 后面必须紧跟描述，不能只写标签不填内容

最常被忽略的是语言模式与工具链的绑定关系：Doxygen 插件不认 Python 文件，pdoc 解析不了 C++ 注释，TypeDoc 对 JS 文件静默失败。别指望一个插件通吃所有语言，先看文件后缀、再看语言标识、最后选工具，顺序错了，后面全白搭。