PhpStorm仅生成JSDoc注释，文档由jsdoc工具生成；光标须置于函数/类声明行最左侧触发自动生成；箭头函数、解构参数等不支持自动补全；需手动配置Live Templates并修正变量表达式；文件头注释与JSDoc无关，应通过File and Code Templates配置；JSDoc仅为元数据，不提供类型安全。
PhpStorm 本身不生成最终的 HTML 文档，它只负责生成符合 JSDoc 规范的代码注释；真正生成可浏览文档的是外部工具 jsdoc 命令行程序。搞混这点，后续所有操作都会卡在“为什么点几下没出网页？”上。
光标必须放在函数/类声明正前方才能触发
不是在函数体内、不是在空行、也不是在 function 后面——必须紧贴在声明行最左侧（例如 function calculate 这一行开头，光标在 f 前）。此时输入 /** 再按 Enter，才会激活 JSDoc 框架生成；否则只会插入普通多行注释。
- 类方法同理：光标需放在
public/static等修饰符前，或直接放在function关键字前 - 箭头函数、
const fn = () => {}形式不支持自动生成，PhpStorm 不识别为可文档化函数 - 解构参数（如
{ id, name }）或 rest 参数（...args）常被漏掉，@param行需手动补全类型和描述 -
this不会被自动识别为上下文对象，@this标签必须手写
改 Live Templates 让 /** + Enter 真正好用
默认模板太简陋，连基础 @param 都可能为空。要让它适配真实项目，得进 Settings → Editor → Live Templates → JavaScript 手动编辑：
- 新建模板缩写建议设为
jsdoc，适用范围选Everywhere in JavaScript - 变量
$FUNCTION_NAME$默认不生效，必须点Edit variables，把表达式设为methodName() -
@param行别硬写占位符，用 Groovy 脚本动态提取：groovyScript("return _1?.collect { it.split(' ')[-1] }.join(', ') ", methodParameters()) - 返回值判断要谨慎：
@returns行建议勾选Skip if the field is empty，避免无返回时仍生成空行
文件头注释和 JSDoc 是两套机制，别混用
文件头（作者、日期、描述）走的是 File and Code Templates，和函数级 JSDoc 注释无关。配置路径是：Settings → Editor → File and Code Templates → Files → JavaScript File：
立即学习“PHP免费学习笔记（深入）”；
- 可用变量：
${USER}、${NAME}、${YEAR}-${MONTH}-${DAY}、${HOUR}:${MINUTE}（别用${TIME}，某些系统不刷新） - 不要写
@file—— JSDoc 规范里没有这个 tag；想标归属，用@module my-app或自然语言描述更稳妥 - 团队要求加 license 或版本号？在这里统一加，新建文件时自动带上，比每次手敲可靠
最易被忽略的一点：JSDoc 注释只是“元数据”，它本身不执行、不校验、不保证类型安全。你写了 @param {number} id，但传个字符串进去，运行时照样崩——它只为 IDE 提示、文档生成和静态分析服务。别指望靠注释挡住错误，该加 TypeScript 类型的地方，一个都不能少。
