必须安装 ID 为 njpwerner.autodocstring 的 Python Docstring Generator 扩展，禁用其他 docstring 类扩展，重启 VSCode 并设为 Python 语言模式，手动配置 style（如 google）、quoteStyle、addReturnType 和 addTypeHints，通过快捷键或命令面板触发生成，且函数需有完整签名和规范类型注解。
装错扩展是第一个也是最大的坑
很多人卡在第一步：装了 AutoDocstring（ID: adamcharnock.autodocstring）或名字带“autodocstring”的其他变体，结果怎么配 python.docstringGenerator.style 都不生效。真正要用的是 Python Docstring Generator，ID 必须是 njpwerner.autodocstring——作者是 Nils Werner，但发布 ID 和界面名称容易混淆。
安装前务必做三件事：
- 在 VSCode 扩展市场搜索
Python Docstring Generator，点开详情页确认 ID 是njpwerner.autodocstring - 禁用所有其他 docstring 类扩展（尤其是
AutoDocstring、autoDocstring、docstring-generator），避免快捷键冲突或行为覆盖 - 安装后重启 VSCode，且确保当前文件语言模式右下角显示为
Python（不是 Plain Text 或其他）
必须手动设置 style，否则生成的 docstring 是残缺的
这个扩展默认不识别函数签名，也不会自动填参数名、类型或返回值。如果你没配置 python.docstringGenerator.style，它只会生成空壳，比如："""Args: :param : :return:""" —— 缺字段名、无缩进、类型全空。
正确做法是在设置里搜 python.docstringGenerator.style，选 google 或 numpy；同时建议顺手配好：
• python.docstringGenerator.quoteStyle 设为 """（双引号）
• python.docstringGenerator.addReturnType 设为 true（否则 return 类型不写）
• python.docstringGenerator.addTypeHints 设为 true（若函数有类型注解，会自动提取）
立即学习“Python免费学习笔记（深入）”；
触发方式不是输 """ 回车，而是快捷键或命令面板
这是和 AutoDocstring 的本质区别：Python Docstring Generator 不监听 """ 输入事件，它只响应显式调用。
两种可靠触发方式：
- 光标放在函数定义行或函数体第一行，按
Ctrl+Shift+P（Win/Linux）或Cmd+Shift+P（Mac），输入Generate Docstring回车 - 给命令绑定快捷键：在键盘快捷键设置里搜
Generate Docstring，设成比如Alt+D（避开和其他扩展冲突）
注意：光标不能在函数体中间或注释里，必须对齐到 def 行或函数首行缩进位置，否则识别失败，报错 No function signature found
生成结果依赖函数签名完整性
它不会猜参数类型，只从已有代码里提取。如果函数没写类型注解，addTypeHints 就没用；如果参数用了 *args / **kwargs，google 风格下会生成 *args 和 **kwargs 字段，但 numpy 风格默认不处理它们，得手动补。
常见兼容性问题：
- 带装饰器的函数：确保
@decorator在def上方紧邻，否则可能解析失败 - lambda 或嵌套函数：不支持，会提示
Not supported for lambda or nested functions - 返回值是 Union 或 Optional：类型字符串会被原样写入，不会简化（比如
Union[str, None]不会转成Optional[str]）
真正难搞的从来不是装插件，而是函数本身没写清楚类型注解、没规范缩进、或者混用了装饰器和 type hint 语法——这些地方一塌糊涂，再好的生成器也救不回来。
