DocBlockr 的 /** 触发失效根本原因是光标未在函数/变量声明行开头或文件类型未被识别为支持语言；参数名错乱因正则匹配签名不标准；Vue 中失效因 .vue 默认 scope 不匹配；自定义模板需严格使用 EJS 语法及限定变量。
DocBlockr 的 /** 触发失效，按完回车没反应
根本原因通常是光标没停在函数/变量声明行的开头，或者当前文件类型没被 DocBlockr 识别为支持语言。
实操建议：
- 确保光标在函数定义行最左侧（比如
function foo($a, $b)这整行的任意位置，但不能在注释里或空行） - 检查右下角状态栏显示的语言模式是否正确（如 PHP、JavaScript、Python），DocBlockr 默认只对
source.php、source.js、source.python等 scope 生效 - 如果用了自定义后缀（如
.inc或.ctp），需在 Atom 设置 → DocBlockr →Language Specific Settings里手动添加 scope 映射 - 禁用其他冲突插件（尤其是同样监听
/**的 snippets 或 autocomplete 工具）
生成的注释参数名错乱，比如写成 @param {string} arg0
DocBlockr 本身不解析实际参数类型，它只靠正则从函数签名里“猜”参数名。一旦签名格式不标准，就容易崩。
实操建议：
- 避免在参数间加多余空格或换行，比如
function test( $a , $b )容易让正则匹配失败 - PHP 中带默认值的参数（如
$flag = true）会被截断成$flag，但= true部分会被丢掉——这是预期行为，不是 bug - JavaScript 箭头函数（
(a, b) => {}）和 TypeScript 类型标注（(a: string, b?: number)）默认不支持，需配合docblockr-js扩展或改用jsdoc-parse类工具 - 想强制指定参数名？直接手敲
@param行再按Tab，DocBlockr 会补全后续字段
怎么让 DocBlockr 支持自定义模板（比如加作者、版权、版本号）
它支持通过配置项 docblockr.template 注入自定义文本，但必须严格遵循 EJS 语法，且变量名固定。
实操建议：
- 打开 Atom 设置 → Packages → DocBlockr → Settings →
Template输入框 - 填入类似：
/** * <%= description %> * @author <%= author %> * @since <%= date %> */
- 可用变量只有
description、author、date、return、params，多一个都无效 -
author值来自 Atom 全局设置里的Core > Author Name，不是 Git 用户名 - 模板里不要写 JS 逻辑（如
if判断），DocBlockr 不执行 JS，只做简单替换
为什么在 Vue 单文件组件里 <script> 块中按 /** 没反应
因为 Atom 默认把 .vue 文件识别为 text.html.vue，而 DocBlockr 只在 source.js 或 source.ts 等 scope 下激活。
实操建议：
- 安装
language-vue插件，并在 Atom 设置 → Core →File Encoding下确认.vue关联的是该语法包 - 手动触发 scope 切换：按
Ctrl+Shift+P（Win/Linux）或Cmd+Shift+P（Mac），输入Editor: Log Cursor Scope，看光标所在位置输出是否含source.js - 若仍是
text.html.vue，可在config.cson里加强制映射：'*.vue': 'source.js': ['<script[^>]*lang=["\']?js["\']?[^>]*>', '<script[^>]*type=["\']?text/javascript["\']?[^>]*>']
- 更省事的做法：在
<script>标签里加lang="js"，DocBlockr 就能自动识别
复杂点在于 scope 识别和模板变量边界非常窄，稍一越界就静默失败。别指望它理解 JSDoc 3 的所有标签，也别给它塞复杂逻辑——它就是个带点智能的文本补全器。
