VSCode悬停文档不生效，主因是语言服务器未正确解析注释：①languageId识别错误（右下角非目标语言）；②缺少jsconfig.json/tsconfig.json或配置不当；③JSDoc/docstring格式不规范（如空行、字段名不匹配、风格不符）；④未保存文件或插件劫持hover响应。
自定义悬停文档不会因改个设置就生效——它依赖语言服务解析注释，不是靠 editor.hover.enabled 这类开关控制的。
为什么改了 settings.json 悬停还是没变化
VSCode 的悬停内容由语言服务器（LSP）动态生成，不是静态配置项。你改 editor.hover.enabled 或 editor.hover.delay 只影响“是否弹出”和“延迟多久”，不决定“弹出什么”。真正决定内容的是：
- 当前文件的
languageId是否被正确识别（右下角显示 Plain Text？点它手动选 JavaScript/Python） - 项目根目录是否存在
jsconfig.json或tsconfig.json（哪怕空文件也必须有） - JSDoc / docstring 是否紧贴函数定义上方、无空行、格式规范（如 Python 必须含
Args:字段） - 是否安装并启用了对应语言服务器（如 Python 用 Pylance，不是基础 Python 扩展）
JSDoc 和 docstring 怎么写才被识别
不是所有注释都会进悬停框。语言服务器只认特定结构：
- JavaScript/TypeScript：必须用
/** */，且紧贴函数声明上一行，中间不能有空行；@param、@returns字段名要和参数名一致（大小写敏感） - Python：Pylance 默认只解析 Google 或 NumPy 风格 docstring，例如：
"""Args:x (int): 第一个参数"""；单行#注释或"""x: int"""不会被提取 - TypeScript 接口/类型别名：支持
/** */注释，但需在tsconfig.json中启用"compilerOptions": {"checkJs": true}（JS 文件中）
修改后为什么悬停还是旧内容
悬停提示不会实时监听注释变更。常见卡点：
- 改完 JSDoc 或 docstring 后，**必须保存文件（Ctrl+S）**，语言服务器才会重新解析 AST 并更新缓存
- 如果函数定义在另一个 workspace 文件夹里，而当前窗口未激活该文件夹，悬停可能读不到最新注释——此时用
Ctrl+Shift+P → Documentation: Show Documentation强制刷新 - 某些插件（如 GitHub Copilot、Sesame AI）会劫持 hover 响应，禁用它们再试
自定义内容只能靠扩展？先确认是不是真需要
95% 的“想自定义”场景，其实只是注释没写对或语言服务没起来。只有当你需要注入外部数据（比如从内部 API 拉取接口说明）、展示 DSL 语义、或渲染非标准字段时，才需开发扩展。此时关键点是：
-
documentSelector必须与真实languageId完全匹配（typescript≠javascript） - 返回的
vscode.Hover内容要用new vscode.MarkdownString(text, true)构造，否则_、*等符号不转义会导致整个提示空白 -
provideHover函数内禁止同步 I/O（如fs.readFileSync），必须用Promise包裹异步操作
最常被忽略的一点：悬停内容是“按文件+位置”缓存的，改了注释不保存，或者 languageId 错配，再怎么调设置都没用。
