因package control在企业内网或受限网络下常卡在“installing…”状态，手动安装可绕过网络校验，适用于离线环境、ci构建机或需固定版本的场景。
为什么手动安装 DocBlockr 而不是用 Package Control？
因为 Package Control 有时会因网络策略、代理或证书问题卡在“Installing…”状态，尤其在企业内网或国内部分 ISP 环境下。手动安装绕过网络校验，直接落地 DocBlockr 插件文件，适合离线环境、CI 构建机或需要固定版本的团队部署。
注意：DocBlockr 依赖 Python 运行时（Sublime Text 内置 Python 3.8+），不兼容 Sublime Text 2；若你用的是 ST4，确认已启用 Python 插件（默认开启）。
手动下载并放置插件目录的完整路径
从 GitHub 官方仓库获取稳定版源码（非 release zip，而是 master 分支最新 commit）：
- 访问
https://github.com/spadgos/sublime-jsdocs（DocBlockr的实际维护地址） - 点击绿色 “Code” 按钮 → “Download ZIP”
- 解压后重命名文件夹为
DocBlockr（必须完全一致，大小写敏感） - 放入 Sublime Text 的
Packages目录：
– Windows：%APPDATA%\Sublime Text\Packages\
– macOS：~/Library/Application Support/Sublime Text/Packages/
– Linux：~/.config/sublime-text/Packages/
重启 Sublime Text 后，在命令面板（Ctrl+Shift+P）输入 DocBlockr，能看到相关命令即表示加载成功。
自定义注释模板的关键配置项
打开 Preferences → Package Settings → DocBlockr → Settings – User，填入 JSON 配置。以下字段直接影响生成效果，容易被忽略：
-
"jsdocs_extra_tags"：追加的标签，支持{{date}}和{{datetime}}占位符，但{{datetime}}需要系统 locale 支持 UTF-8 时间格式，否则可能乱码 -
"jsdocs_function_description"：设为false可跳过首行“函数功能简述”，避免冗余空行 -
"jsdocs_indentation_spaces"：设为2或4，匹配项目缩进风格；若设为0，会导致@param对齐失效 -
"jsdocs_spacer_between_sections"：设为true才会在@param和@returns之间空一行
示例最小可用配置：
{
"jsdocs_extra_tags": ["@author ${1:YourName}", "@date {{date}}"],
"jsdocs_function_description": false,
"jsdocs_indentation_spaces": 2,
"jsdocs_spacer_between_sections": true
}
JavaScript 注释触发失败的常见原因
敲 /** + Enter 没反应？不是插件没装好，大概率是当前文件类型没识别对：
- 确认右下角状态栏显示的是
JavaScript（不是Plain Text或HTML）；点击它可手动切换 - JSX 文件需额外设置：在
Settings – User中加入"jsdocs_scope": "source.js, source.jsx" - ES6 class method 前加
/**不生效？因为DocBlockr默认只识别function和const/let声明的箭头函数；class 内部方法需启用"jsdocs_parse_class_methods": true - 光标必须严格位于函数声明**正上方一行**，且该行为空或仅含空白符；前面有注释或代码会中断解析
复杂点在于：模板逻辑和语法解析器耦合紧密，改一个 tag 可能影响整个 block 结构；建议每次只调一个参数，保存后立即测试，避免多变量叠加导致行为不可预测。
