webstorm的jsdoc自动生成仅在函数声明正前方触发，光标需紧贴function或const fn =左侧；输入/**后按enter才补全@param/@returns，箭头函数、解构参数等需手动补全或用fix doc comment修复。
光标必须紧贴函数名左侧才能触发 /** + Enter
WebStorm 的 JSDoc 自动生成不是“ anywhere 输入 /** 都行”，它只在函数/类/方法声明语句的正前方生效。比如 function foo(a, b) 这一行，光标得放在 f 前面（即行首或紧贴 function 左侧），输入 /** 后按 Enter 才会补全 @param 和 @returns。
常见失败场景：
- 光标在函数体内、空行、注释后——不触发
- 箭头函数
const bar = (x) => {}——不识别为声明，需先转成function或用Fix Doc Comment - 解构参数
({ a, b })或 rest 参数...args——@param行常为空或错写，得手动补@param {Object} options这类描述 - 类方法中
this不被当作参数——@this标签必须手写
Fix Doc Comment 是补救漏注释的唯一可靠方式
当你已经写了部分代码、光标不在声明行前、或注释格式混乱时，Ctrl+Shift+A 搜 Fix Doc Comment 是最稳的选择。它不依赖光标位置，而是向上扫描最近的函数/方法/字段声明，再智能合并已有注释。
它的实际行为：
- 保留你已写的
@param x，只补缺失的参数项 - 如果函数体里有
return但没返回值，可能误加@returns——得手动删 - 不推导复杂类型，比如
@param {string | number}或泛型T，必须手写 - 对 getter/setter、async 函数、重载签名支持有限，容易漏
@returns {Promise}这类关键信息
Live Templates 自定义 method* 要改变量表达式才可用
默认模板里的 $functionName$ 在函数声明行前是空的，因为 WebStorm 认为它只在函数体内有效。想让它在声明处也生效，必须进 Edit variables 把表达式设为 methodName()。
其他关键设置点：
- 模板适用范围选
Statements或Everywhere in JavaScript，否则新建文件时method*+Tab不触发 -
@param行不能动态适配参数个数——模板里写三行，函数只有两个参数，就得手动删掉一行 - 别用
@file：JSDoc 规范不认这个 tag；标文件归属用@module或自然语言更稳妥 -
$USER$、$DATE$、$HOUR$:$MINUTE$可用，但$TIME$在某些系统上不刷新
jsdoc 命令行生成 HTML 文档必须手动执行
WebStorm 本身不生成 HTML 文档，所有“点一下出网页”的期待都会落空。真正构建文档的是外部 jsdoc 工具，必须走命令行。
典型流程和易错点：
- 全局安装：
npm install -g jsdoc（或项目局部装：npm install jsdoc --save-dev） - 执行：
jsdoc src/**/*.js -d docs，其中src/**/*.js是源码路径，docs是输出目录 - 报错
Cannot find module 'jsdoc'：说明没装，或装了但 shell 没识别到全局 bin 路径 - 生成空白页或缺内容：多半是源码路径写错，或 JSDoc 注释语法有硬伤（比如
@param缺类型、@returns后没空格） - 想省事？把命令写进
package.json的scripts里："doc": "jsdoc src/**/*.js -d docs"，然后运行npm run doc
真正容易被忽略的是：JSDoc 注释一旦生成，就参与类型推导和补全。如果 @param {string} 写成 string（漏了花括号），后续调用处的类型提示就会失效——比不写还误导人。
