autodocstring插件无反应的四大原因及解决：①python路径未正确配置，需在settings–user中设置绝对路径的"python_binary"；②docstring格式不匹配项目规范，可通过右键或配置文件切换为numpy等风格；③光标未置于def行或函数体首行；④中文参数名或类型注解导致ast解析失败，应改用英文标识符。
AutoDocstring插件装完没反应？检查Python环境绑定
插件本身不自带Python解释器，它依赖你系统里已有的python或python3命令能正常调用。常见现象是按下Ctrl+Shift+2（Windows/Linux）或Cmd+Shift+2（macOS）后光标不动、无弹窗、控制台报FileNotFoundError: [Errno 2] No such file or directory: 'python'。
解决方法：
- 打开Sublime Text → Preferences → Settings – User，确认
"python_binary"路径正确（例如"python_binary": "/usr/local/bin/python3"，macOS常用；Windows可填"python_binary": "C:\Python39\python.exe"） - 如果用pyenv或conda，别直接写
python，得用绝对路径，比如~/.pyenv/versions/3.11.5/bin/python（Linux/macOS）或C:Users ameMiniconda3envsmyenvpython.exe（Windows） - 终端里运行
which python3或where python确认路径，再粘贴进配置——别漏掉.exe后缀
注释模板选错导致格式混乱：docstring风格必须匹配项目约定
AutoDocstring默认生成Google风格，但如果你的项目用的是NumPy、reStructuredText或Sphinx格式，直接插入会和团队规范冲突，甚至被CI工具（如pydocstyle）报错。
切换方式很简单：
- 右键代码 → AutoDocstring → Configure docstring format，选
numpy、restructuredtext或sphinx - 也可在
Preferences → Package Settings → AutoDocstring → Settings – User里加一行："docstring_format": "numpy" - 注意：函数参数顺序、返回值写法、空行规则各风格差异很大。比如Google风格用
Args:，NumPy用Parameters，reST用:param字段
光标位置不对就生成失败：必须严格放在def行或函数体内第一行
AutoDocstring只识别两种合法触发位置：
-
def关键字所在行的任意列（哪怕光标在def后面空格上） - 函数体内部、第一个非空行（比如
"""前或pass那行），但不能在注释块中间、字符串里、或缩进错误的位置
典型失败场景：
- 光标停在函数调用行（如
my_func(1, 2)）→ 插件完全不响应 - 光标在已有docstring的
"""内部 → 它不会覆盖，而是报Docstring already exists - 函数体第一行是
if True:这种语句 → 插件可能误判为非函数体开头，跳过生成
中文文档支持弱：类型提示和参数名含中文时容易崩
AutoDocstring底层用AST解析，对非ASCII字符处理不稳定。当函数参数名是中文（如def 处理数据(输入文本: str) -> dict:），或类型注解含中文（-> "用户信息字典"），常出现SyntaxError或生成空docstring。
稳妥做法：
- 参数名、返回类型坚持用英文（PEP 484也要求类型提示用英文标识符）
- 中文说明写在docstring正文里，而不是类型注解中
- 若必须用中文变量名，先临时改成英文触发生成，再手动改回并补全中文描述
真正麻烦的不是生成不出来，而是生成了但类型字段错位或缺失——这种问题得靠肉眼核对，插件本身不校验语义。
