docblockr仅在光标位于函数/变量声明行且语言模式为source.js、source.php等支持scope时触发；.vue文件需手动映射text.html.vue到source.js，正则解析参数名不支持箭头函数、解构及类型标注。
Atom 本身不生成代码注释，必须靠插件；目前唯一稳定可用的是 docblockr，但它只在严格满足两个条件时才触发：光标必须落在函数/变量声明行上，且文件语言模式（scope）必须是它支持的类型（如 source.js、source.php）。
docblockr 按 /** 没反应？先检查光标和语法模式
很多人以为输入 /** 回车就能出注释，其实不是。它只响应“当前行是函数/类/变量定义行”这个状态，不看上下文，也不解析 AST。
- 光标必须在整行任意位置，但该行得是声明行——比如
function foo(a, b) {、const bar = (x) => x * 2;、class Baz {}；停在空行、函数体内部、注释里都不行 - 右下角状态栏必须显示
JavaScript、PHP或Python等，不能是Plain text或text.html.vue；Vue 文件需手动切换 grammar 到Vue Component（对应 scopesource.vue） - 用
.inc、.ctp等非标准后缀时，得进Packages → docblockr → Language Specific Settings手动把后缀映射到source.php等 scope - 如果装了
autocomplete-plus或其他监听/的插件，可能劫持输入；临时禁用它们再试
参数名错乱或缺失？正则匹配有硬限制
docblockr 不读 TypeScript 类型、不解析解构、不处理箭头函数体内的逻辑——它只用正则从函数签名字符串里“抠”参数名。格式一歪，就丢信息。
- PHP 中
function test($a , $b = null)的多余空格会让参数截成$a和$b，但= null被丢掉；这是设计如此，不是 bug - JS 箭头函数
const fn = ({ x }, [y]) => {}会被识别为两个参数{ x }和[y]，不会进一步拆解；想准确提取，得改写成function fn(obj, arr)并手补@param - 带类型标注的 TS 写法
(a: string, b?: number)默认不支持；需额外装docblockr-js扩展，或接受参数名被识别为a:、b? - 要强制指定参数名？直接手敲
@param {string} username，再按Tab，docblockr会自动补全后续字段（如@returns）
怎么加 @author、@since 或自动日期？模板变量很窄
docblockr 的自定义模板只认固定几个变量：description、author、date、return、params。多一个都无效，也不执行 JS 逻辑。
- 模板填在
Packages → docblockr → Settings → Template，必须以/**开头、*/结尾，例如：/**\n * \n * @author \n * @since \n */
-
author值取自Settings → Core → Author Name，不是 Git 配置；留空就真为空 -
date是插入时刻的字符串，不随保存刷新；想更新得再次触发（快捷键或命令面板） - 别写
这类判断——docblockr不执行 JS，只会原样输出
Vue / TS 文件怎么让文件头注释生效？scope 是关键门槛
docblockr 默认不响应 .vue 或 .ts 文件的快捷键，因为它的 scope 判断极严：只有 source.vue、source.ts 才走 JS/TS 模板逻辑，text.html.vue 直接跳过。
- 确认右下角显示的是
Vue Component（对应 scopesource.vue），不是HTML (Vue)（即text.html.vue）；点状态栏手动切换 - TS 文件同理，选
TypeScript（scopesource.ts），别选TypeScriptReact（scopesource.tsx）除非你已配好对应规则 - 文件头注释不能自动插入，得手动触发：光标放第一行 →
Cmd+Shift+P（macOS）或Ctrl+Shift+P（Win/Linux）→ 输入Docblockr: Insert file header→ 回车 - 模板中注释风格固定为
/** */，所以只适用于 JS/TS/Vue 的<script></script>块；<template></template>区域要用<!-- -->，得另配插件
真正容易被忽略的是：所有“自动”都依赖 scope 精确匹配，而 Atom 的 grammar 识别常被忽略；一次失效，八成是右下角那个小标签没点对。
