vscode默认不支持一键生成jsdoc，需装插件如document this（快捷键ctrl+shift+p→document this）或better jsdoc（默认ctrl+alt+d），且光标须置于函数名正上方空行、函数签名明确方可准确生成。
VSCode 默认不支持 JSDoc 快捷生成，需手动触发或装插件
VSCode 本身没有内置的 Ctrl+Alt+D 或类似一键生成 JSDoc 的功能。你敲 /** 后回车，只有在光标紧贴函数定义上方、且函数有明确签名（如 function foo(a, b)）时，才会自动补全基础 JSDoc 模板；否则只会插入空的 /** */ 块。
常见错误现象：光标放在函数内部、或函数是箭头函数但没写参数名（如 const fn = () => {}），/** + 回车后什么也不生成。
- 确保光标严格位于函数声明/表达式正上方一行，且该行为空
- 函数必须含可推断的参数名和返回值（ES5 函数声明最稳，箭头函数建议写成
const fn = (a, b) => {}） - 若用 TypeScript，类型信息会增强 JSDoc 字段推断（如自动生成
@param {string} a）
推荐插件：Document This 或 Better JSDoc
Document This 是老牌稳定选择，支持 JS/TS，按 Ctrl+Shift+P → 输入 Document This: Document This 即可生成完整 JSDoc；Better JSDoc 更轻量，支持自定义模板，且默认绑定快捷键 Ctrl+Alt+D（Windows/Linux）或 Cmd+Option+D（macOS）。
使用场景：团队统一注释风格、批量补全旧代码、配合 ESLint 规则 valid-jsdoc 检查时尤其有用。
- 安装后重启 VSCode，首次使用前检查快捷键是否被其他插件占用
-
Better JSDoc的模板可通过设置jsdoc:template自定义，例如添加@since或公司内部字段 - 对 async 函数，
Document This会自动加@returns {Promise<void>}</void>，而Better JSDoc默认不推断 Promise 类型，需手动补
函数签名不明确时，JSDoc 生成内容常出错
比如 const handler = (e) => {...}，插件可能把 e 当作 @param {any} e，而非更准确的 @param {Event} e；再比如无返回值的函数，可能漏掉 @returns {void}。
这不是插件 bug，而是 JS 动态特性导致的类型不可知。TypeScript 用户应优先用 @type 或接口定义，而非依赖 JSDoc 推断。
- 箭头函数参数若缩写（如
({id}) => {}），插件通常无法解析解构字段，会生成@param {Object} arg0 - 类方法中，
this上下文不会被自动标注，需手动加@this {MyClass} - 导出函数若用
export default function foo()，部分插件识别不稳定，建议改用具名导出 +export { foo }
生成后务必人工核对三处关键字段
JSDoc 不是“生成即完事”的装饰，真正影响文档质量和 IDE 提示的是 @param、@returns、@throws 这三项。VSCode 的智能提示（如 Ctrl+Space）和 TS 类型检查都依赖它们。
-
@param类型必须与实际入参一致，尤其注意number | undefined和number?的区别 -
@returns若函数可能 throw，应明确写@returns {Promise<t>} — or throws</t>，而非只写类型 -
@throws很少被自动生成，但对关键错误路径（如网络请求失败）必须手动补充，否则调用方无法感知风险
复杂点在于：同一个函数在不同调用路径下可能返回不同类型，这时 JSDoc 需用 @returns {T | U} 或联合类型描述，而插件几乎从不生成这类逻辑判断——得靠人看代码补。
