Sublime Text安装DocBlockr注释插件提高规范性

# Sublime Text 装 DocBlockr 没反应？90% 的问题都出在这三点 DocBlockr 装完没动静，不是插件坏了，而是触发条件没满足——语法模式、光标位置、ST4 兼容性，这三点卡住了绝大多数人。 ## 怎么确认 DocBlockr 真正生效了 它不靠“安装完成”就自动工作，必须同时满足三个条件： 1. **当前文件被识别为支持语言**：右下角状态栏显示 `Ja vaScript`、`TypeScript`、`PHP` 等，而不是 `Plain Text`。如果是 `Plain Text`，点它手动切换到对应语言。 2. **光标位于函数/类定义行的任意位置**：不能在空行，也不能在函数体内。最佳位置是函数名所在行。 3. **敲入 `/**` 后直接回车**：注意是 `/**`，不是 `/*` 或 `///`。 如果按了 `/**` 没反应，别急着重装，先检查上面三个点。 **常见误区**： * **箭头函数**：原版 DocBlockr 可能不解析 `const fn = (a, b) => {}` 这类语法。可以尝试改成 `function fn(a, b) {}` 的格式，或者直接使用 `DocBlockr-Alt` 分支。 * **光标位置**：确保光标在函数签名那一行，而不是在它上方或下方的空行。 ## 为什么 /** 回车后 @param 是空的 DocBlockr 的核心工作是提取参数名，**它不推断类型**。 当你写下 `function getUser(id, options)` 并触发注释生成时，它会得到： ```ja vascript /** * [getUser description] * @param {any} id [description] * @param {any} options [description] * @return {any} [description] */ ``` 注意 `{any}` 只是一个占位符，不是插件自动识别出来的类型。 **你需要手动补充类型信息**： * 把 `{any}` 改成具体的类型，如 `{string}`、`{Object}`。 * 对于解构参数 `({ a, b })` 或带默认值的参数 `(a = 1)`，DocBlockr 提取的参数名可能会错乱，生成后需要人工校对。 * 写在代码里的 JSDoc 内联注释（如 `/** @type {number} */`），DocBlockr 不会读取——它只分析函数签名的文本结构。 ## Sublime Text 4 用户必须装 DocBlockr-Alt 如果你用的是 ST4，并且遇到了类似 `AttributeError: 'NoneType' object has no attribute 'groups'` 的错误，这不是配置问题，而是**原版 DocBlockr 与 ST4 的 API 不兼容**。 **解决方案**： 1. 通过 Package Control 卸载原版 `DocBlockr`。 2. 安装 `DocBlockr-Alt` 分支。这个版本专为 ST4 维护，修复了兼容性问题，并支持更新的语法。 3. 安装后，建议关闭所有文件再重新打开，以避免旧缓存干扰。 ## 自定义作者、日期等字段不生效的真正原因 很多人修改了用户设置，却发现生成的注释块里没有出现自定义的标签（如 `@author`、`@since`）。问题通常出在配置项的键名或格式上。 **正确配置方法**： 1. 打开 `Preferences → Package Settings → DocBlockr → Settings – User`。 2. 添加或修改以下配置（**注意键名和格式**）： ```json { // 注意是 "jsdocs_extra_tags"，不是 "jsdoc_extra_tags" 或 "extra_tags" "jsdocs_extra_tags": [ "@author YourName", "@since 2026-01-01" ] } ``` 3. 保存文件。**配置里不能有尾随逗号**，否则 JSON 语法错误会导致整个设置失效。 4. 修改后，需要在一个新的函数上方重新敲 `/**` 回车，旧的注释块不会自动更新。 **最关键的一点**：DocBlockr **不处理**已存在的注释块，也**不监听**函数签名的修改。每次生成注释，都是一次全新的触发。想提高效率，与其花时间调试复杂的参数识别，不如确保光标放对、符号敲对、分支选对——这比什么都快。