<p>Docblockr 安装与使用需认准主插件 spadgos 版本 ≥3.4.0，光标须在函数声明行且语言 scope 正确（如 source.vue/source.ts），文件头模板需以 /** 开头并配置 Author Name，Vue/TS 特殊语法需额外扩展支持。</p>
Docblockr 装不上？先确认你用的是哪个安装入口
直接在 Atom 设置里搜 docblockr 就能装，但很多人卡在第一步——搜出来的是 docblockr 还是 docblockr-js 或 docblockr-python？前者是主插件，后两者是语言扩展，不能单独装。装错就白忙活。
实操建议：
- 打开 Atom →
Ctrl+,（Win/Linux）或Cmd+,（Mac）→ 切到 Install 标签页 - 搜索框输入
docblockr，认准作者是spadgos、版本号 ≥ 3.4.0（2026 年最新稳定版） - 别点
docblockr-js单独安装——它只是增强 JS 支持，没主插件根本跑不起来 - 如果搜不到，检查是否开了代理或网络异常；离线环境请用
apm install docblockr命令（确保apm已加入 PATH）
/** 按了没反应？光标和语言 scope 才是关键
装完插件，写 /** 再按 Tab 没反应，不是插件坏了，而是它根本没“看到”你写的函数。
常见错误现象：
- 光标不在函数声明行最左侧（比如前面有空格、缩进，或停在注释里）
- 文件后缀是
.vue或.ts，但右下角状态栏显示的是text.html.vue或source.tsx，而非source.vue或source.ts - 用了非标准后缀（如
.inc、.ctp），Docblockr 默认不识别
实操建议：
- 把光标移到
function foo(a, b) {这整行任意位置，但必须是该行且不能在已有注释内 - 右下角点击语言标识 → 手动选
Vue Component或TypeScript，别信自动识别 - 自定义后缀支持：Settings → Packages →
docblockr→ Language Specific Settings → 添加 scope 映射，例如{"*.inc": "source.php"}
文件头注释怎么加？别信“file-header”插件
搜 “Atom 文件头插件”，90% 推荐的 atom-file-header 已停更多年，新版 Atom 直接跳过加载，装了也白装。
唯一可靠方案是用 Docblockr 自带的文件头功能：
- Settings → Packages →
docblockr→ Template 输入框粘贴模板（必须以/**开头、*/结尾） - 模板变量只认
、、，多一个变量名都无效 -
author值取自 Atom 全局设置：Settings → Core → Author Name，不是 Git 配置 - 新建文件后，把光标移到第 1 行 →
Ctrl+Shift+P（Win/Linux）或Cmd+Shift+P（Mac）→ 输入Docblockr: Insert file header回车
注意：它不支持保存自动触发，也没 API 让你绑定到 Ctrl+S —— 想“伪自动”，得配合 script 插件写一行命令，但稳定性不如手动触发。
Vue / TS 里注释生成失败？scope 和语法块要分开看
在 .vue 文件的 <script> 块里敲 /** 没反应，不是插件问题，是 Docblockr 只处理 JS/TS 语法块，不处理 HTML 或模板部分。
实操建议：
- 确保光标在
<script>标签内部，且当前编辑器语法模式是source.js或source.ts（右下角确认） -
<template>或<style>块里敲/**必然失效——那里该用<!-- -->或/* */，Docblockr 不管 - TypeScript 箭头函数
const fn = (a: string): void => {}默认不解析参数名，想补全得手敲@param行再按Tab - Vue 的
<script setup>语法目前不被 Docblockr 原生支持，需搭配docblockr-vue等社区扩展（但兼容性不稳定）
真正容易被忽略的是：哪怕所有设置都对，只要文件没被 Atom 正确 assign scope，Docblockr 就当它不存在——别跳过右下角那个小标签的确认步骤。
