VSCode原生注释快捷键仅支持基础行/块注释，无法生成文档级注释；需安装koroFileHeader等插件实现文件头、函数JSDoc及中文注释自动填充。
VSCode 自带的注释快捷键只处理基础语法，不生成文档级注释；要自动加文件头、函数 JSDoc 或中文注释，必须装插件。
Ctrl + / 和 Shift + Alt + A 的真实能力边界
这两个是 VSCode 原生快捷键，但作用非常有限：
-
Ctrl + /（macOS 是Cmd + /）只做单行注释：选中多行后，每行前加//、#或//等，取决于当前 languageId —— 它不会识别函数结构，也不会补参数说明 -
Shift + Alt + A（macOS 是Shift + Option + A）只对支持/* */的语言生效，比如 JavaScript、TypeScript、Java；在.py里按了没反应，在.html里会逐行加<!--和-->，不是包裹式注释，容易因缩进错位失效 - 它们都不感知函数签名，不提取参数，不更新时间字段，也不支持中文翻译或公司版权模板
koroFileHeader 插件的两个核心快捷键
这是目前最稳定、语言覆盖最全的自动注释插件，2026 年仍在持续维护。它提供两套独立触发逻辑：
- 文件头注释：
Ctrl + Alt + I（Windows/Linux），Ctrl + Cmd + I（macOS）。触发后会在文件顶部插入完整头部，含@Author、@Date、@LastEditTime等，其中Date和LastEditTime字段设为"Do not edit"即可由插件自动填充 - 函数注释：
Ctrl + Alt + T（Windows/Linux），Ctrl + Cmd + T（macOS）。光标必须停在函数名正前方（如function<cursor> fetchData</cursor>），插件才能正确解析参数并生成@param、@return块 - 注意：
Ctrl + Alt + I/T在 macOS 上是Ctrl + Cmd + I/T，不是Cmd + Alt——这个组合键容易按错，尤其在装了 Vim 插件时会被拦截
Document This 和中文翻译插件的分工场景
如果你需要更贴近 JSDoc 规范的函数注释，或者要处理中英文混杂的注释内容，得换工具：
-
Document This插件用Ctrl + Alt + D（macOS 是Cmd + Alt + D），适合 TypeScript 项目：它能准确提取function foo(a: string, b?: number): boolean里的类型，但@description字段永远为空，必须手动填 - 中文注释不是靠“汉化 UI”，而是靠
Caiyun Translator这类语义翻译插件：需填 API key，禁用detect source language，显式设translate.defaultSourceLanguage为en、translate.defaultTargetLanguage为zh；否则遇到// init config可能误判为中文源语言，输出乱码 -
Chinese-comment不翻译，是“写”中文注释：光标停函数名上按快捷键，直接生成带中文@param说明的模板，适合团队强制要求中文文档的场景
配置错一个字段，整个注释就失效
koroFileHeader 的settings.json里有三个关键对象：fileheader.customMade（新建文件头）、fileheader.cursorMode（函数注释模板）、fileheader.configObj（全局开关）。最容易出问题的是：
- 把
"Date": "Do not edit"写成"Date": "do not edit"（大小写敏感），插件就不再自动填时间 - 在
fileheader.cursorMode里删了param字段，结果函数注释里连@param标签都不生成 - 没关掉 Vim 扩展的
handleKeys配置，导致Ctrl + Alt + T被吞掉，看起来像快捷键“失灵” - 在
.tsx文件里函数注释失败？检查 languageId 是否为typescriptreact，不是typescript——VSCode 看的是 editor 模式，不是文件后缀
