docblockr 在 sublime text 4 上已停止维护，安装失败或注释无效；应改用专为 st4 重写的 doxydoxygen，它支持多语言、lsp 集成，并需注意模板语法（jinja2）、键位冲突及配置项适配。
DocBlockr 在 Sublime Text 4 上已不再维护，官方仓库明确标注为 “unmaintained”，直接安装会失败或生成错误注释。
DocBlockr 安装失败的典型现象
运行 Package Control: Install Package 后搜 DocBlockr，列表里压根不出现；或者强行从 GitHub clone 进 Packages 目录，重启后按 Ctrl+Shift+D（Windows/Linux）或 Cmd+Shift+D（macOS）没反应，控制台报错 AttributeError: 'NoneType' object has no attribute 'groups' —— 这是插件解析函数签名时在 ST4 的新 API 下崩溃了。
- ST4 默认启用
sublime_lib和异步插件加载机制，而 DocBlockr 依赖旧版sublime_plugin.TextCommand同步行为 - 它无法识别 ST4 中
view.substr(view.word(point))返回空字符串的新逻辑，导致正则匹配失败 - 即使降级到 ST3，新版 Python 3.8+ 运行时也会因
inspect.getargspec被弃用而抛ValueError
替代方案：使用 DocBlockr 的精神继承者 —— DoxyDoxygen
它专为 ST4 重写，支持 Python/JS/PHP/C++ 等主流语言，能正确提取参数名、类型、返回值，并兼容 LSP 插件（如 pylsp 或 typescript-language-server）提供的语义信息。
- 安装方式：打开命令面板 →
Package Control: Install Package→ 搜DoxyDoxygen，选中回车即可 - 触发注释：把光标放在函数定义行（如
def fetch_user(id: int) -> dict:），按Ctrl+Alt+D（Windows/Linux）或Cmd+Alt+D（macOS） - 关键配置项：
doxy_doxygen_comment_trigger可设为/**或///，避免和已有注释风格冲突 - 若 JS 函数带解构参数（如
(options = { timeout: 5000 })），需开启js_extract_destructured_params才能正确列出options.timeout
自定义注释模板时最容易漏掉的兼容点
DoxyDoxygen 允许改 DoxyDoxygen.sublime-settings 里的 templates 字段，但直接复制 DocBlockr 的模板会出问题 —— 它的变量语法不兼容。
- DocBlockr 用
${1:description}，DoxyDoxygen 必须写成{description}（无美元符、无序号） -
@param的循环必须用{% for param in params %}@param {param.type} {param.name} {param.desc}{% endfor %}，不是${params} - 如果模板里写了
@return {return_type}，但函数实际没返回值（-> None或无标注），DoxyDoxygen 默认会跳过整行 —— 想强制显示得加{% if return_type %}...{% endif %} - 路径
Packages/DoxyDoxygen/templates/下的自定义文件名必须以.j2结尾（Jinja2 格式），否则加载失败且无提示
真正卡住人的从来不是“怎么装”，而是“为什么装了不生效”—— 大多因为混用了 ST3 时代的模板语法，或没关掉旧插件残留的 key binding 冲突。检查 Preferences → Key Bindings 里有没有其他插件占用了 Ctrl+Alt+D，比反复重装更省时间。
