docblockr仅在光标位于函数/变量声明行且语言模式为source.js等支持scope时触发；.vue需映射text.html.vue到source.js；箭头函数、解构、ts类型需手动补全注释；@author等需修改snippets文件；块注释需绑定editor:toggle-block-comment。
DocBlockr 触发失败？先看光标和语言模式
DocBlockr 不是“输 /** 就出注释”，它只在两个条件同时满足时才工作：光标必须落在函数/变量声明行的任意位置（比如 function foo(a, b) 这整行），且 Atom 右下角显示的语言模式必须是它支持的 scope，例如 source.js 或 source.jsx。常见失效场景包括：
- 光标停在空行、函数体内部或参数括号里——它不向上/向下查找最近的函数
- .vue 文件的
<script></script>块默认是text.html.vue，不在 DocBlockr 激活列表里；需进 Settings → Packages → DocBlockr → Language Specific Settings，把text.html.vue映射到source.js - 用 .ts、.jsx 等扩展名时，右下角若显示
JavaScript (Babel)或TypeScript是 OK 的，但若显示Plain text，按Ctrl+Shift+P→ 输入Grammar: Set Language手动切换
箭头函数、解构、TS 类型怎么写注释
DocBlockr 不解析 AST，只靠正则从函数签名字符串里“抠”参数名，所以对现代 JS 语法支持有限：
-
const fn = (a, b) => {}默认不触发；得写成声明式const fn = function(a, b) {}，或装docblockr-js插件 -
function f({ x }, [y])会被识别为两个参数{ x }和[y]，不会进一步拆解；@param {Object} options后需手动补@property {string} options.x - 带默认值的
function g(a = 1, b = 'test')，正则可能截断为a和b，但丢掉默认值部分——这是设计如此，不是 bug - TypeScript 类型标注如
(a: string, b?: number)完全被忽略；@param类型得手敲，比如@param {string} a
怎么让 @author、@since 自动填上
DocBlockr 自带模板只认固定变量：description、author、date、return、params。想加 @author 或 @since，不能靠全局设置，得改 snippet 文件：
- 路径是
~/.atom/packages/docblockr/snippets/javascript.cson（macOS/Linux）或%USERPROFILE%\.atom\packages\docblockr\snippets\javascript.cson（Windows） - 找到
docblock对应的body数组，在末尾追加一行：'@author ${1:your.name@example.com}' -
author值取自 Atom 全局设置里的 Core > Author Name，不是 Git config 的user.name - 别写
这类 JS 判断——DocBlockr 不执行逻辑，只会原样输出
块注释和行注释快捷键怎么配才不翻车
Ctrl+/ 默认调用的是 editor:toggle-line-comments，行为完全由当前 grammar 决定。想用 /* */ 块注释，得手动绑定 editor:toggle-block-comment：
- 打开 Config → Open Config Folder，编辑
keymap.cson - 加入（以 JS/JSX/TS 为例）：
'.source.js, .source.jsx, .source.ts, .source.tsx': 'ctrl-alt-/': 'editor:toggle-block-comment'
- scope 必须精确匹配；查当前真实 scope 的方法：
Ctrl+Shift+P→Editor: Log Cursor Scope，看控制台输出（如source.js.jsx meta.function.js） - 别用泛用选择器如
*，否则可能在设置页或终端误触发
最常被忽略的一点：DocBlockr 的参数提取能力是正则级的，不是语法级的。哪怕你把函数写得再规范，只要括号内有换行、多空格、注释符号或非 ASCII 字符，就可能崩。真要 100% 控制字段，不如光标停在函数名后直接敲 @param 再 Tab —— 它会自动补全后续字段，比等自动生成更稳。
