VSCode 在 Vue 项目中无法可靠自动生成 JSDoc 注释，因其不解析 Vue 模板和组合式 API 语义；需配合 Volar、显式类型定义（如 defineProps<{...}>）、正确语言模式及紧邻函数的注释格式才能提升准确性。
VSCode 本身不解析 Vue 模板或组合式 API 的语义，所谓“自动生成注释”在 Vue 项目中基本不可靠——它只能对 setup() 里的普通函数或导出的 const 函数做有限推断，对 defineProps、defineEmits、ref 声明、computed 或模板中的插值表达式完全无感知。
Vue 单文件组件里 /** 回车为啥没反应？
这不是插件坏了，是 VSCode 默认把 .vue 文件识别为“HTML”或“Vue”语言模式，而原生 JSDoc 补全只在 JavaScript/TypeScript 语言服务激活时工作。常见断点：
- 右下角状态栏显示的是
Vue而非TypeScript或JavaScript—— 点击切换成后者才能触发内置/**补全 - 没装 Volar（官方推荐）或 Vetur（已弃用），导致
setup()内部无法被正确解析为 TS 上下文 - 函数写在
<script setup>里但用了箭头函数 + 解构：const handleClick = ({ id }) => {...}，Document This 或 Auto Comment Blocks 会漏掉id -
defineProps是运行时宏，VSCode 插件看不到类型定义，除非你显式写了defineProps<{ msg: string }>()并启用 Volar 的“Take Over Mode”
想让 @param 和 @returns 有点用，得先稳住类型声明
Vue 的注释生成准确率，直接取决于类型信息是否可静态提取。没有类型，插件就只能猜：
vue-component-analyzer
下载
递归分析 Vue 项目组件依赖，从入口文件生成组件层级图，支持 Vue 2/3，输出组件名、文件路径和属性。适用于分析组件结构、排查依赖或了解项目架构。
- 用
defineProps时，必须搭配泛型或interface，比如defineProps<{ visible: boolean; title?: string }>()，否则 Document This 会输出@param {any} props -
defineEmits同理，写成defineEmits<{ (e: 'confirm'): void; (e: 'cancel', reason: string): void }>()才能被部分插件识别为事件参数 - 组合式函数（如
useFetch）若未导出类型，外部调用处的@returns就是{any}；建议在函数末尾加as const或返回类型标注 - 别依赖
ref()的自动类型推导——写const count = ref<number>(0)</number>，比ref(0)更容易被插件捕获
真正能落地的半自动流程：snippets + Volar + 手动校验
放弃“全自动”，改用可控路径：
立即学习“前端免费学习笔记（深入）”；
- 在
javascript.json或typescript.json代码片段里加一条："vue-function-jsdoc": { "prefix": "vdoc", "body": [ "/**", " * @description ${1:description}", " * @param {${2:type}} ${3:name} - ${4:brief}", " * @returns {${5:type}} ${6:brief}", " */" ] } - 光标停在
setup()内函数名前，按Ctrl+Shift+P→ 输入Insert JSDoc comment（VS Code 内置命令），它比插件更稳定 - Volar 开启
experimental.enableAutoImport后，/**补全能识别导入的类型，比如从@vue/runtime-core导入的Ref - 导出的
const函数（如export const formatTime = (ts: number) => ...）最稳妥——这类函数签名清晰，Document This 和 ESDoc 都能抓准ts参数和返回类型
最容易被忽略的细节：JSDoc 注释块必须紧贴函数声明上方，中间不能有空行；<script setup> 中的函数如果前面隔了 const props = defineProps(...)，那注释就得写在 props 前面，否则 Volar 和 jsdoc CLI 都会跳过它——这个空行问题导致 Vue 项目文档生成失败率远高于纯 TS 项目。
