WebStorm运行JSDoc自动生成开发文档的步骤

很多人在用 WebStorm 写 JSDoc 注释时都会遇到同一个困惑：明明按照教程敲了 /** + Enter，也生成了注释框架，可怎么就是看不到网页版的 index.html 文档？其实这里有个关键认知需要先理清——WebStorm 本身只负责在代码里插入注释块，它并不直接输出静态网页文档。真正把注释变成漂亮 HTML 页面的，是外部命令行工具 jsdoc。所以，如果在 IDE 里点了一圈没看到网页，别急着怀疑操作，而是很可能漏掉了第二步。

WebStorm不生成HTML文档，只生成注释框架

这一点值得反复强调：WebStorm 的核心能力是帮你快速生成符合 JSDoc 规范的注释模板，比如自动补全 @param、@returns 这些字段。但它不会帮你跑一次构建，更不会自动输出 index.html。很多人以为在编辑界面里点个“生成文档”就能看到网页，实际上那个功能只是生成注释框架本身。真正把注释解析成独立网页的，还得靠 jsdoc 这个独立工具——它读取源码中的注释，然后输出成完整的静态站点。

光标放对位置才能触发 /** + Enter

这是日常开发中最容易翻车的地方。注意：光标必须紧贴函数/类/方法声明行的最左侧——比如 function calculate() 这一行的开头，光标放在 f 前面。输入 /** 然后立刻按 Enter，WebStorm 才会自动补全出 @param 和 @returns 的占位。如果光标偏了一个字符，往往就只生成一个空的 /** */ 块，啥都不自动填充。

• 箭头函数（比如 const fn = (a) => {}）不会被自动识别，需要先把箭头函数转成普通 function 形式，或者用 Ctrl+Shift+A 搜索 Fix Doc Comment 手动修复。
• 解构参数（例如 ({ id, name })）和 rest 参数（...args）经常被漏掉，生成的 @param 行会缺失这些参数，只能手动补全类型和说明。
• 类方法中如果使用了 this，WebStorm 不会自动生成 @this 标签，同样需要手写。

jsdoc 命令行生成静态文档

安装好 jsdoc 之后，真正开始生成网页文档的是终端里的那条命令。这里有几个常见操作和坑：

• 全局安装：npm install -g jsdoc；局部安装：npm install jsdoc --sa ve-dev。推荐局部安装，避免污染全局环境。
• 基本命令示例：jsdoc src/**/*.js -d docs。其中 src/**/*.js 是源码路径（支持通配符），docs 是输出目录名。
• 常见报错 Cannot find module 'jsdoc'：先确认是否在项目根目录下运行命令，或者检查 node_modules/.bin 是否已加入 $PATH 环境变量。
• 如果想换主题（比如 docdash）：先执行 npm install docdash，然后在命令中加上参数 -t node_modules/docdash 即可切换。

Live Templates 自定义 method* 时容易翻车

想通过 method* + Tab 快速生成 JSDoc 注释模板？这个技巧很实用，但有两个关键设置必须调好，否则 $functionName$ 变量永远为空。

• 进入 Settings → Editor → Live Templates → Ja vaScript，新建一个模板，缩写填 method*。
• 点击 Edit variables，把 $functionName$ 的 Expression 改为 methodName()——这一步是核心，默认值不生效。
• 适用范围要选 Statements 或 Everywhere in Ja vaScript，如果只选了 Function declaration，那么箭头函数、方法表达式等都无法触发。
• 另外，@param 行不建议硬编码固定数量，因为当函数有多个参数时，固定占位符会导致需要手动删除多余的条目。更好的做法是用 Groovy 脚本动态生成参数列表。

最后别忘了：注释一旦生成，就会参与 TypeScript 或 IDE 的类型推导。比如 @param {string} 写成 string（缺了大括号），后续调用处的类型提示就会直接失效——这比不写注释还危险。所以细节上多花一分钟，能省下后面排查类型的几小时。