document this 仅支持函数声明的 ast 解析，对解构参数、箭头函数表达式（如 ({id, name}) => {}）、类中箭头函数成员等均无法提取参数名或返回类型，需手动补全；tabnine/copilot 仅做 token 补全，描述空泛且类型推断错误率高；可靠方案是使用 vs code 内置 jsdoc 命令配合自定义 snippet，严格保证注释紧贴函数声明上方，避免空行，并手动补充泛型与业务语义。
Document This 为什么对解构参数和箭头函数失效
它只解析函数声明的 AST 节点，遇到 ({ id, name }) => {} 或 const fn = () => "ok" 这类写法时，根本无法提取参数名或返回值类型。插件会生成空的 @param 或直接跳过——不是 bug，是设计限制。
常见错误现象：光标停在箭头函数名上按 Ctrl+Alt+D，结果什么都没出来；或者对 function getUser({ userId }) 生成的注释里漏掉 userId 字段。
- 解构参数必须手动补全，
Document This不做字段展开 - 箭头函数表达式体（
=> "value"）不被识别为可注释函数节点 - 类方法中用箭头函数定义的成员（
onClick = () => {}）同样被忽略
Tabnine / Copilot 补出来的 @param 为什么常是废话
它们不是注释生成器，而是基于上下文的 token 补全模型。输入 /** 后按回车，Copilot 可能输出 @param {string} input - the input，这种描述对维护毫无价值。
实测中，Tabnine 对 async 函数的 @returns 推断错误率超 40%，比如把 Promise<user></user> 写成 User；Copilot 完全无法识别自定义 Hook 的返回结构，比如 useAuth() 返回的 { user, login, logout } 会被笼统标为 @returns {any}。
- 参数描述依赖变量名本身，
id就写 “the id”，data就写 “the data” - 不理解业务含义，
status: 'pending' | 'done'不会标注状态含义 - 副作用（如调用
localStorage.setItem）完全无感知，不会加@sideEffect
真正能落地的半自动流程：vscode-snippets + 内置命令
放弃“全自动”，用可控步骤替代不可靠猜测。核心是让机器填骨架、人来填血肉。
先在 javascript.json 片段里定义：
/**
* ${1:description}
* @param {${2:type}} ${3:name} - ${4:desc}
* @returns {${5:returnType}} ${6:brief}
*/
写完函数后，光标停在函数名上，按 Ctrl+Shift+P → 输入 Insert JSDoc comment（VS Code 内置命令，无需插件），自动套用片段并定位光标到 ${1:description}。
- 必须紧贴函数声明上方，中间不能有空行，否则
jsdocCLI 和 TS 编译器都会忽略 -
jsdoc -r ./src -d ./docs --verbose会明确告诉你哪些函数因缺@returns被跳过 - 配合
eslint-plugin-jsdoc规则（如require-description）在保存时提示补全
jsdoc CLI 导出文档时为什么总漏函数
最常见原因是注释位置不对：JSDoc 块和函数声明之间夹了空行、注释写在函数体内、或用了 // 单行注释代替 /** */。
另一个隐蔽问题是泛型推导失败。比如 TypeScript 中 function fetchList<t>(): Promise<t></t></t>，jsdoc 默认不解析泛型，@returns 会变成 {any[]}，某些校验规则会因此跳过该函数。
- 检查
--verbose输出里是否出现 “skipping function X: no @returns tag” - 泛型函数需手动写
@returns {Promise<user>}</user>，不能依赖自动推导 - 导出前用
tsc --noEmit验证 TS 类型是否被正确识别，避免类型擦除干扰
真正卡住团队落地的，从来不是工具选错，而是注释和函数之间那一个不该存在的空行。
