Atom无讲解式批注功能，需分三类操作：行内注释、结构化文档块（如Docblockr生成JSDoc）、独立注解层（如atom-code-annotations浮动标签），类型选错即无效。
Atom 本身不提供“讲解式批注”功能，所谓“代码讲解”必须拆解为三类真实可用的操作：行内注释、结构化文档块、独立注解层——选错类型，就等于没做。
Ctrl+/ 没反应？先看右下角是不是 Plain Text
Atom 的注释行为完全依赖 grammar（语法作用域），不是靠文件后缀猜的。一个 .js 文件如果右下角显示 Plain Text，按 Ctrl+/ 就只会插入斜杠，不会加 //。
- 点击右下角语言名 → 手动选
JavaScript (Babel)或Python等具体 grammar - 临时验证：按
Ctrl+Shift+P→ 输入Grammar: Show Grammar看当前 scope 名 - 保存为正确后缀（如
.py）才能让 Atom 自动绑定 grammar，.txt永远是纯文本 - JSX/TSX 中光标落在 HTML 标签内时，
Ctrl+/可能插<!-- -->而非//，这是 grammar 切换导致的，不是 bug
想写 JSDoc 或 PHPDoc？装 Docblockr，别手敲
Docblockr 是唯一能自动提取函数签名、参数、返回值并生成标准文档块的插件。它不替代行注释，而是补足“接口说明”这一层。
- 安装后，在函数定义上方输入
/**+Tab，立刻生成带@param和@returns的块 - 支持语言：JavaScript、PHP、Python（Google/NumPy 风格）、Java，但不支持 Vue 单文件组件中的
<script></script>块，需手动切 grammar - 自定义模板要改
snippets.cson，例如为 JS 添加快捷前缀：docb→ 展开为完整 JSDoc 框架 - 注意：它只处理函数/方法，对变量、常量、class 声明无效；想注释 class，得用
atom-code-annotations
需要在代码旁加解释性贴纸？用 atom-code-annotations
atom-code-annotations 提供的是“非侵入式批注”：不修改源码，只在编辑器右侧或行尾叠加浮动标签，适合教学、Code Review 或临时说明。
- 安装后，选中一行 → 右键 →
Add Annotation，输入文字即生效，支持 Markdown 渲染 - 注释内容不进 Git，但可导出为 JSON 备份；与
todo-show冲突，两者不能共存于同一项目 - 搜索和过滤靠插件内置面板，不依赖正则；但无法跳转到其他文件的同名变量，仅限当前打开文件
- 它和
language-todo无关——后者只高亮// TODO:这类标记，不存储任何额外信息
真正容易被忽略的是：Atom 没有“全局批注视图”。所有注释都绑定在文件路径+行号上，一旦重命名或移动文件，atom-code-annotations 的批注就丢失，Docblockr 生成的 JSDoc 则随代码保留。要不要写，取决于你批注的目的是“给人看”，还是“给机器读”。
