VSCode插件（如Document This）仅生成JSDoc注释模板，不生成最终文档；真正生成可读文档的是typedoc、jsdoc等外部工具，需人工补全注释并正确配置才能产出有效API文档。
VSCode插件本身不生成“开发说明文档”，它只负责解析代码注释并转换格式；真正产出可读文档的是外部工具（如 typedoc、jsdoc、doxygen）或你写的 Webview 渲染逻辑。别指望点一下按钮就出来一份《开发者手册》，那是混淆了“注释模板生成”和“文档构建”两个阶段。
Document This 生成的是 JSDoc 模板，不是文档
它只在函数上方插入/** */块，填入参数名、类型占位符，比如：@param {string} name - 。这些内容必须人工补全才有意义——AI 或插件无法知道name是用户登录名还是设备序列号。如果你跳过这步直接跑typedoc，生成的 API 文档里会满屏@returns {any}和空@description。
- Document This 对箭头函数表达式体（
const fn = () => {}）完全无响应 - 解构参数（
({ id, meta }) => {}）会被识别成单个arg0，字段注释全丢 - TS 泛型（
Promise<t></t>）推导失败，一律变成any，typedoc会警告但继续输出 - 注释必须紧贴函数声明上一行，中间有空行 →
typedoc和 TS 编译器都忽略它
typedoc / jsdoc 才是文档生成主力，但依赖正确注释位置
typedoc 不读源码，只读 JSDoc 注释块；它根本不管你的函数有没有实现，只要注释语法合法就照单全收。所以常见错误是：本地跑typedoc成功，CI 上失败——因为 CI 环境没装node_modules，而typedoc 默认从node_modules/typescript找解析器，路径不对就报Cannot find module 'typescript'。
- 确保
typedoc.json里"entryPoints"指向.ts文件，不是.d.ts或.js - 用
--ignoreCompilerErrors绕过类型检查失败，但别在正式构建中开这个开关 - 如果项目用了
monorepo结构，typedoc默认不递归子包，得手动加"entryPoints": ["packages/*/src/index.ts"] - 输出目录
"out": "docs/api"别设成"out": "./docs"，后者会导致typedoc把整个项目根目录当输出路径，删掉node_modules
Webview 预览 ≠ 文档发布，二者要分开设计
你在插件里用vscode.WebviewPanel实时渲染 Markdown，只是给开发者看个样子；它不生成静态文件，也不校验链接是否有效。想对外发布文档，必须调用vscode.workspace.fs.writeFile()把内容写进磁盘，再配好docs/目录的 Git 提交规则。
- Webview 中用
marked渲染时，sanitize: true必须开，否则用户注释里的<script></script>会被执行 - 导出
.md前要过滤掉@internal标记的函数，否则把私有 API 暴露出去 - 不要用
fs.writeFileSync，VSCode 插件主线程禁止同步 I/O，得用vscode.workspace.fs.writeFile()Promise 版本 - 导出路径建议用
vscode.window.showSaveDialog()让用户选，而不是硬编码./docs/README.md——项目可能没这个目录
最常被忽略的其实是注释和代码的同步节奏：改了函数签名但忘了更新@param，typedoc照样生成，但文档已失效；Webview 预览也看不出问题，因为只渲染当前文本。靠人眼比对不现实，得在 CI 里加typedoc --watch或用eslint-plugin-jsdoc做提交前检查。
