webstorm的/**+enter仅在函数声明行最左侧触发，光标须置于function关键字前；箭头函数需转换或手动补全，解构与rest参数、@this、@param类型均需手写，且类型必须用大括号包裹。
光标位置不对，/** + Enter 就不生效
WebStorm 只在函数、类、方法声明行最左侧触发 JSDoc 自动补全。比如 function calculate(a, b) { 这一行，光标必须落在 f 前面（即行首），输入 /** 后立刻按 Enter 才能生成带 @param 和 @returns 的框架。光标在行中、行尾、或声明行缩进后，都会失效。
箭头函数（如 const fn = (a) => {}）默认不被识别，要么先转成 function 形式，要么用 Ctrl+Shift+A 搜 Fix Doc Comment 手动补全。
- 解构参数（
({ id, name })）和 rest 参数（...args）不会自动生成@param，必须手动补全类型和说明 - 类方法里
this不会自动加@this，得手写 -
@param类型必须用大括号包裹，比如@param {string} name；写成@param string name会导致后续类型推导失效
Live Template 里 $functionName$ 总是空的
想用 method* + Tab 快速生成函数注释，关键在变量表达式设置。进入 Settings → Editor → Live Templates → JavaScript，新建模板后点 Edit variables，把 $functionName$ 的 Expression 改成 methodName()，否则它永远为空。
适用范围不能只选 Function declaration，得选 Statements 或 Everywhere in JavaScript，否则在对象方法、模块导出函数里无法触发。
- 别硬写固定数量的
@param占位符，多参数时删起来麻烦；可用 Groovy 脚本动态生成（但多数人直接手补更省事） - 模板里
@description留空或写占位符，避免每次都要删
文件头注释和 JSDoc 注释是两套机制，别混用
新建 .js 文件时自动带作者/日期，走的是 File and Code Templates → Files → JavaScript File 路径，不是 Live Template。模板里必须用 ${USER}、${YEAR}-${MONTH}-${DAY}、${NAME} 这类变量，手写字符串（如 "zhangsan"）不会替换。
Live Template（比如输 cmt + Tab）只适合在已有文件里插函数说明、组件文档这类非强制内容，没法控制新建文件的首行。
- 扩展名必须填
js，否则右键新建时看不到这个模板 - 模板建在
Includes或Code栏下无效，只对代码片段插入起作用 - 如果要支持更新时间（
@update），得配 File Watcher，Live Template 本身不感知文件修改
jsdoc 命令不报错但没输出 HTML
WebStorm 本身只生成注释文本，不生成 index.html。真正产出静态文档靠命令行工具 jsdoc，不是 IDE 内置功能。
常见卡点：执行 jsdoc src/**/*.js -d docs 报 Cannot find module 'jsdoc'，大概率是因为没在项目根目录运行，或 node_modules/.bin 不在 $PATH 中。局部安装时建议用 npx jsdoc 避免路径问题。
- 全局安装：
npm install -g jsdoc；局部安装：npm install jsdoc --save-dev - 换主题（如 docdash）：先
npm install docdash，再加参数-t node_modules/docdash - 路径通配符注意 shell 差异，Windows 命令行可能需写成
src\**\*.js
注释一旦生成，就参与类型推导——类型写错比不写还危险，比如漏掉大括号、拼错类型名，会让调用处的提示直接消失。
