悬停不显示JSDoc类型提示，需确认WebStorm是否解析JSDoc：先启用JavaScript Language Service并配置jsconfig.json（含"checkJs": true），确保光标置于function声明行最左侧触发/**+Enter，@param等类型必须用{}包裹且大小写正确，最终以Ctrl+Q面板显示“From JSDoc”为准。
悬停不显示JSDoc类型提示？先确认WebStorm是否真在解析它
WebStorm默认开启悬停提示，但Show quick documentation on mouse move只是“展示开关”，不是“解析开关”。真正决定你能否看到@param {string}或@returns {Promise<number>}的关键，在于IDE是否把这段注释当成了类型信息源——这依赖两个前提：JavaScript Language Service已启用，且项目配置了jsconfig.json（或tsconfig.json）并启用了checkJs: true。
常见错误现象：鼠标悬停只显示函数名和空括号getPrice()，没有参数类型、没有返回值、没有描述文字。
- 检查
Settings → Languages & Frameworks → JavaScript，确认JavaScript language version设为ES6+（推荐ES2022），且Language service处于启用状态 - 项目根目录必须存在
jsconfig.json，内容至少包含：{ "compilerOptions": { "checkJs": true }, "include": ["**/*.js"] } - 若用TypeScript，
tsconfig.json中也需有"checkJs": true，否则JS文件里的JSDoc不会被深度解析 - 删除
node_modules和.idea后重开项目，避免旧缓存干扰类型服务加载
光标位置不对，/** + Enter根本不会生成JSDoc框架
很多人以为只要输入/**再按Enter就能补全，结果什么都没发生——问题不在设置，而在光标没放对地方。WebStorm的JSDoc模板触发是严格绑定语法节点的，只对函数声明、类声明、方法定义这些“顶层符号”生效。
典型失败场景：const getPrice = (a, b) => a * b;这种箭头函数，光标放哪都不行；obj.method = function() {}这种赋值式写法也不识别。
- 必须把光标放在
function关键字正前方（比如function getPrice(a, b) {这一行最左边），然后输入/**再按Enter - 类方法要放在
methodName() {这一行开头，不能放在class A {那行 - 变量声明如
/** @type {string} */ let name;不走模板，得手写或用Ctrl+Alt+/（仅限声明语句） - 解构参数
({ id, name })和rest参数...args不会被自动识别为@param，必须手动补全
写了JSDoc但悬停还是没类型？检查大括号和语法细节
JSDoc类型提示失效，80%是因为类型标注格式不合法。WebStorm依赖TypeScript语言服务解析@param和@returns，而TS只认标准JSDoc语法——尤其强调大括号{}不能丢，类型名大小写不能错，空格不能多也不能少。
错误示例：@param string price（缺大括号）、@param {String} price（String不是TS内置类型）、@returns number（缺大括号）——这些都会让整个注释块被忽略。
-
@param和@returns后面必须紧跟{类型}，类型名用小写：{string}、{number[]}、{User | null} - 复杂对象用
@typedef提前定义，再在@param里引用：@param {User} user，否则{Object}这种泛型无法触发属性提示 - 第三方库类型要靠
@types/xxx包支持，比如@param {import('axios').AxiosRequestConfig}才能正确推导 - 别在
@param里写中文描述时混入英文类型：@param {string} 用户名→ 应拆成@param {string} username - 用户名
Ctrl+Q弹出的面板才是类型提示的最终验证场
鼠标悬停受限于展示空间和性能，很多嵌套类型、长泛型、交叉类型根本显示不全。真正判断JSDoc是否生效，得靠Ctrl+Q（macOS是Ctrl+J）调出的完整文档面板——它能滚动、高亮、跳转，而且会明确标出“From JSDoc”或“From @types”来源。
如果Ctrl+Q里也看不到类型，说明解析链断在了某处：可能是jsconfig.json没生效，也可能是当前文件被exclude了，还可能是node_modules里混入了非官方@types导致冲突。
- 按
Ctrl+Q后看左下角状态栏：显示“Loading…”说明语言服务卡住；显示“From JSDoc”说明注释已识别；显示“From node_modules/@types/xxx”说明走了类型库 - 面板里出现
any或unknown，大概率是@type写错了，或者checkJs没开 - 想确认某个变量是否被正确推导，直接在它上面按
Ctrl+Shift+P（Quick Definition），看能不能定位到@typedef定义处 - 禁用所有非官方插件（尤其是“中文API助手”类），再
Invalidate Caches and Restart，排除干扰
JSDoc类型提示不是写完注释就自动生效的魔法，它是一条从语法识别→配置加载→服务解析→UI渲染的完整链路。任何一个环节松动，悬停里就只剩函数名和空括号。最稳的验证方式永远是Ctrl+Q，而不是盯着鼠标划过的那一秒。
