Atom注释功能依赖正确的grammar，右下角状态栏显示的grammar名决定Ctrl+/行为、DocBlockr触发及TODO高亮；需手动选择匹配scope（如JavaScript (Babel)），.vue中块须映射text.html.vue→source.js。
Atom 识别代码注释不是靠“猜”，而是严格依赖当前文件绑定的 grammar（语法解析规则）。一旦 grammar 错了，Ctrl+/ 可能只插入 // 字符，/** 不触发 DocBlockr，// TODO: 也不高亮——所有注释相关功能都会静默失效。
怎么看当前 grammar 是否正确
右下角状态栏显示的内容就是 Atom 当前认定的 grammar 名。它不等于文件后缀，也不等于你“以为”该是的语言。
- 点一下那个标签（比如显示
Plain text或HTML (Rails)），从弹出菜单里手动选对的 grammar（如JavaScript (Babel)而非仅JavaScript） - 临时验证：按
Ctrl+Shift+P（Win/Linux）或Cmd+Shift+P（macOS），输入Grammar: Show Grammar，看输出是否为预期 scope（如source.js、source.php） - .vue 文件中
<script></script>块默认是text.html.vue，不在多数插件支持列表里，必须进Settings → Packages → DocBlockr → Language Specific Settings手动把text.html.vue映射到source.js
为什么 Ctrl+/ 有时注释、有时不注释
这个快捷键的行为由当前 grammar 的 toggle-comments 配置决定，不同语言定义不同：
-
source.js默认用//行注释；source.css用/* */块注释；source.python用# - 如果 grammar 是
text.plain，Ctrl+/会退化为纯文本插入，不带任何语言感知逻辑 - 某些 grammar（如
source.gfm）压根没定义注释行为，按键无响应 - 快捷键冲突常见于装了多个 snippets 插件时，可临时禁用
autocomplete-plus排查
DocBlockr 生成 /** 注释失败的硬性条件
它只在两个条件同时满足时才工作，缺一不可：
- 光标必须落在函数/方法/变量声明行本身（例如
function foo(a, b) {这整行），停在空行、注释行或函数体内部都不触发 - 当前 grammar 必须是它明确支持的 scope，如
source.js、source.php、source.python；source.ts和箭头函数、解构参数不被解析 - 非标准后缀（如
.inc、.ctp）需在 DocBlockr 设置中手动添加 scope 映射 - 输入
/**后按Tab是触发点，但前提是上述两条已满足；否则只会原样插入字符
// TODO: 不高亮？先检查 language-todo 的基础前提
language-todo 是高亮的底层支撑，它不分析语义，只做模式匹配：
- 必须安装
language-todo，否则todo-show只能搜到文字，但编辑器里不会变色、不带图标 - 匹配规则严格：
// TODO: fix this✅，// TODO:fix this❌（冒号后必须有空格） - 支持大小写不敏感前缀：
// todo:、/* FIXME */、# HACK等共 10+ 种，但全部依赖 grammar 正确识别 - 若高亮失效，90% 是因为右下角显示
Plain text或HTML，而不是source.js等对应语言 scope
最常被忽略的一点：Atom 不会自动根据文件内容推断语言。哪怕你写满屏 function 和 const，只要右下角显示 Plain text，所有语言感知型注释功能就等于没装。确认并修正 grammar 是一切的前提，不是可选项。
