document this 和 esdoc 常失效，因其依赖静态分析而无法正确处理解构参数、泛型和箭头函数；korofileheader 需手动配置 custommade 和 functiontemplate 才适配规范；vs code 内置 jsdoc 命令更稳定，支持解构与 async，但要求注释紧贴函数无空行；ai 插件描述泛滥且不准，应以 snippets+内置命令+人工补全为最佳实践。
为什么 Document This 和 ESDoc 在现代 JS/TS 项目里常失效
它们不是“智能理解业务”，而是靠静态语法分析推导 @param 和 @returns，一遇到解构参数、泛型、箭头函数表达式体就漏掉或写错。比如：({ id, name }) => {} 中的 id 和 name 不会被 Document This 识别；Promise<user></user> 在 ESDoc 里大概率变成 @returns {any}；const fn = () => "ok" 这类写法根本不会触发注释生成。
koroFileHeader 插件怎么配才真正好用
它不依赖语言服务，靠模板 + 光标位置生成，可控性高，但必须手动配对才能适配项目规范：
-
fileheader.custommade填作者、邮箱等固定字段，避免每次手输 -
fileheader.functiontemplate里用$1、$2占位符匹配参数名和类型，例如：* @param {$1} $2 - $3 -
fileheader.configobj.autoadd设为true，新建文件时自动插头部注释；autoupdate开启后保存会更新@lastedit - JS/TS 模板建议保留
@description和@returns行，哪怕先留空——后续补全比删掉重写成本低
VS Code 内置 JSDoc 生成命令比插件更稳的场景
光标停在函数名上，按 Ctrl+Shift+P → 输入 Insert JSDoc comment，这是 VS Code 自带功能，不装插件也能用，且兼容性最好：
- 支持解构参数（只要函数是声明式写法，如
function foo({ a, b })） - 能识别
async函数并自动加@returns {Promise<...>}</...> - 对 TypeScript 泛型推导有限但比多数插件准，比如
Array<string></string>能被正确捕获 - 唯一硬要求：
/** */注释必须紧贴函数上方，中间不能有空行——否则 TS 编译器和jsdocCLI 都会跳过它
别信 AI 插件自动生成的 @param 描述
Tabnine 和 Copilot 是补全工具，不是注释生成器。实测中它们对参数的描述常是 the input、the value 这类无效内容；对 async 函数的 @returns 推断错误率超 40%；更关键的是，它们完全无法感知自定义 Hook 的返回结构或副作用逻辑（比如 localStorage.setItem 调用）。
真正能落地的做法：用 vscode-snippets 定义基础模板，配合内置命令插入骨架，再人工补 @description 和业务语义——机器负责格式，人负责含义。那个“注释必须紧贴函数声明上方无空行”的细节，80% 的团队文档失败都栽在这儿。
