DocBlockr触发需同时满足光标位于函数/方法/变量声明行且语言模式为source.js等支持scope；.vue文件需手动映射text.html.vue到JavaScript，自定义模板仅支持有限变量。
DocBlockr 触发失败：光标位置和语言模式必须同时满足
DocBlockr 不是“输入 /** 就自动出注释”，它只在两个条件都成立时才工作：光标必须落在函数/方法/变量声明行的任意位置（比如 function foo($a, $b) 这整行），且 Atom 右下角显示的语言模式必须是它支持的 scope，例如 source.js、source.php 或 source.python。
常见失效场景包括：
- 光标停在空行、函数体内部或注释行里——它不识别“下方最近的函数”，只认当前行
-
.vue文件中<script></script>块默认是text.html.vue，不在激活列表里；需进Settings → Packages → DocBlockr → Language Specific Settings手动把text.html.vue映射到source.js - 用
.inc、.ctp等非标准后缀时，得手动加 scope 映射 - 同时启用多个 snippets 插件（如
autocomplete-plus）可能劫持/**输入，建议临时禁用排查
参数名错乱或缺失：正则匹配 ≠ AST 解析
DocBlockr 不解析 AST，也不读 TypeScript 类型或 PHP 8 返回类型，它靠正则从函数签名字符串里“抠”参数名。一旦格式不规整，就容易崩。
典型问题与应对：
- PHP 中
function test($a , $b = null)的多余空格会让正则截断为$a和$b，但丢掉= null部分——这是设计如此，不是 bug - JavaScript 箭头函数
const fn = (a, b) => {}默认不支持；得改写成function fn(a, b) {}或装docblockr-js扩展 - 解构参数
function f({ x }, [y])会被识别为两个参数{ x }和[y]，不会进一步拆解 - 想强制指定参数名？直接手敲
@param {string} username再按Tab，DocBlockr 会自动补全后续字段
Vue 单文件组件中 <script></script> 块不触发：scope 映射是硬门槛
.vue 文件默认被 Atom 识别为 text.html.vue，而 DocBlockr 只在 source.js、source.ts 等 scope 下激活。不映射，就永远不响应。
实操步骤：
- 打开
Atom → Settings → Packages → docblockr → Language Specific Settings - 在
Scope Names输入框中添加text.html.vue - 在对应
Language下拉菜单中选JavaScript（或TypeScript） - 保存后重启 Atom 或重载窗口（
Window: Reload）
注意：仅修改 grammar 设置（如右下角点选 JavaScript）无效，必须走 DocBlockr 的 scope 映射配置。
自定义模板填坑：EJS 变量名和执行逻辑都受限
想加 @author、@since 或自动填日期，不能随便写 JS 逻辑——DocBlockr 只做静态替换，且只认几个硬编码变量。
关键限制：
- 模板填在
Atom Settings → Packages → DocBlockr → Template输入框里，内容类似：/**\n * <%= description %>\n * @author <%= author %>\n * @since <%= date %>\n */
- 可用变量仅限：
description、author、date、return、params；多一个version或copyright都无效 -
author值取自 Atom 全局设置里的Core > Author Name，不是 Git config 的user.name - 别写
这类判断——DocBlockr 不执行 JS，只会原样输出
真正要加公司级字段（如 @internal 或 @license），得去编辑 ~/.atom/packages/docblockr/snippets/javascript.cson 文件，在 docblock 的 body 数组末尾追加新行，而不是靠 template 配置。
