docblockr仅在光标位于函数/方法/变量声明行且语言模式为source.js、source.php等支持scope时触发；.vue文件需手动映射text.html.vue到source.js，正则解析参数名不支持箭头函数、解构及类型标注。
光标位置和文件类型必须同时满足才能触发
DocBlockr 不是“输入 /** 就一定出注释”，它只在两个条件都成立时才工作：光标必须落在函数/方法/变量声明行的任意位置（比如 function foo($a, $b) 这整行），且 Atom 右下角显示的语言模式必须是它支持的 scope，例如 source.js、source.php 或 source.python。常见失效场景包括：
- 光标停在空行或函数体内部——它不识别“下方最近的函数”，只认当前行
- .vue 文件中
<script></script>块默认是text.html.vue，不在 DocBlockr 激活列表里；需手动在设置里把text.html.vue映射到source.js - 用 .inc、.ctp 等非标准后缀时，得进
Atom Settings → Packages → DocBlockr → Language Specific Settings手动加 scope 映射 - 同时启用多个 snippets 插件（如
autocomplete-plus）可能劫持/**输入，建议临时禁用排查
参数名错乱或缺失，本质是正则匹配失败
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 会自动补全后续字段
自定义模板必须严格遵循 EJS + 固定变量名
想加 @author、@since 或自动填日期，不能随便写 JS 逻辑——DocBlockr 只做静态替换，且只认几个硬编码变量：
- 模板填在
Atom Settings → Packages → DocBlockr → Template输入框里，内容类似：/**\n * \n * @author \n * @since \n */
- 可用变量仅限：
description、author、date、return、params；多一个version或copyright都无效 -
author值取自 Atom 全局设置里的Core > Author Name，不是 Git config 的 user.name - 别写
这类判断——DocBlockr 不执行 JS，只会原样输出
为什么 Vue 单文件组件里 <script></script> 块没反应
根本原因是 Atom 把 .vue 文件整体识别为 text.html.vue，而 DocBlockr 默认只监听 source.js、source.ts 等 scope。它不关心你写在哪块标签里，只看当前编辑器的 language mode。
- 临时方案：点右下角语言模式，手动切换成
JavaScript（会丢失 Vue 语法高亮） - 长期方案：进
Atom Settings → Packages → DocBlockr → Language Specific Settings，添加一条："text.html.vue": ["source.js"]
- 注意：这个映射只对
<script></script>块生效；<template></template>和<style></style>仍不支持，别白费劲
最常被忽略的其实是 scope 映射和正则边界——它不智能，只机械匹配。写法越贴近传统函数声明，成功率越高；一上箭头函数、解构、类型标注，就得接受手动补全或换工具。
