VS Code无真正理解业务逻辑的注释插件，“自动生成”实为语法结构填充，效果取决于函数签名清晰度、语言特性支持度及光标位置精准性；Document This等插件因不支持解构参数、TS泛型、箭头函数赋值式及Vue SFC语义而频繁失效，可靠方案是用内置Insert JSDoc comment命令+手动补全+jsdoc CLI验证，且JSDoc必须紧贴函数声明上方无空行。
VSCode 没有真正“自动理解业务逻辑”的注释插件，所谓“自动生成”本质是语法结构填充，效果取决于函数签名是否清晰、语言特性是否被插件支持、光标位置是否精准——盲目依赖 Document This 或 Copilot 生成的 @param 和 @returns，大概率要返工。
Document This 在 JS/TS 中为什么常漏参数或写错类型
它靠解析函数声明的形参列表推导 @param，但对现代写法支持极弱：
- 解构参数如
({\u200b id, name \u200b}) => {}→ 完全识别不出字段，生成空@param行 - TypeScript 泛型返回值如
Promise<user></user>→ 推导成@returns {any}，丢失泛型信息 - 箭头函数赋值式
const fn = () => "ok"→ 不触发注释生成（无 function 关键字） - 函数体为空或只含 return → 插件跳过，不生成模板
它不读代码逻辑，只看 AST 节点。一旦签名不符合传统 function xxx(a, b) 结构，就失效。
Vue <script setup> 里按 Ctrl+Alt+D 没反应的真正原因</script>
不是插件坏了，是 VSCode 根本没把光标所在位置识别为“可注释的函数声明”：
-
defineProps解构、useXXX组合式 API 声明 → 不是标准函数参数，Document This 无法提取 -
setup()函数本身在 <script setup> 中被编译器隐去，没有显式函数名和签名</script> - 光标若停在
const data = ref(null)这类声明行 → 插件找不到“被注释对象”，静默跳过 - 语言模式未正确设为
vue（右下角显示html或plaintext）→ 插件根本不激活
这不是配置问题，是设计限制：插件不支持 Vue SFC 的编译时语义。
比“自动生成”更可靠的做法：内置命令 + 手动补全 + CLI 验证
放弃全自动幻想，用可控步骤保证注释质量和工具链兼容性：
- 写完函数后，光标停在函数名上，按
Ctrl+Shift+P→ 输入Insert JSDoc comment（VS Code 内置命令，无需插件）→ 得到基础模板 - 手动补全
@param类型和描述，尤其注意解构字段、可选参数（[opt]）、Promise 泛型（写全Promise<string></string>） - 运行
jsdoc -r ./src -d ./docs --verbose→ 查看控制台输出哪些函数因缺@returns或格式错误被跳过 - JSDoc 注释必须紧贴函数声明上方，中间**不能有空行**；否则
jsdoc和 TypeScript 编译器均忽略它
这个流程不快，但每处注释都可验证、可追溯、能进 CI。最容易被跳过的，就是那个“不能有空行”的硬性要求——它导致超过七成的团队文档生成失败。
