autodocstring 自动生成文档需满足三个前提：插件正确安装、光标位于函数定义正下方第一行、函数签名完整（含参数名和→返回箭头）；缺一不可。
能自动生成，但必须满足三个前提：插件装对、光标位置准、函数签名有信息。 其他配置都是锦上添花，这三点没对，按多少次 Enter 都不会出文档。
autodocstring 插件安装后不生效？先查这三个硬条件
常见错误现象是输入 """ 后回车，光标直接换行，什么都没生成。这不是插件坏了，而是触发条件没满足：
- 当前文件语言模式必须是
Python（右下角状态栏显示“Python”，不是“Plain Text”或“JSON”） - 光标必须在函数/方法定义的正下方第一行（不能在函数体内部、不能在类定义外、不能在注释行）
- 函数至少要有完整的签名——哪怕没类型提示，也得有参数名和
->返回箭头（def foo():这种空括号函数，autodocstring默认不生成）
Google vs NumPy 风格怎么选？看团队工具链
风格差异不是审美问题，而是影响下游工具能否解析：
-
Google风格（默认）：字段用Args:/Returns:等关键词缩进，Pylance 和大多数 LSP 客户端识别最稳，适合新项目 -
NumPy风格：字段顶格写，用冒号分隔（Parameters、Returns），numpydoc和 Sphinx 构建 API 文档时更友好，老科学计算项目常用 - 别混用：
autodocstring.docstringFormat设为"google"后，所有生成都统一，手动改个别函数风格会导致pylint报invalid-docstring-quotes
类型推断不准？补类型提示比调设置更有效
autodocstring.guessTypes 开关只是辅助，它靠变量名和默认值猜类型（比如 name="xxx" → str），但容易翻车：
- 列表嵌套类型不识别：
data: list会被写成list，不会变成list[dict] - Union 类型常被简化：
Optional[int]可能变成int or None，但格式未必符合 PEP 484 - 真正靠谱的做法：直接写
def process(items: list[str]) -> dict[str, float]:，插件会原样抄进 docstring，不猜、不丢、不歧义
生成后还要手动改？这些字段它默认不填
插件只负责结构和签名映射，以下内容必须人工补全，否则文档就是半成品：
- 函数用途的摘要句（第一行）：插件只留空行或占位符
"""<summary></summary>，你得写清“做什么”，不是“怎么做的” - 参数具体行为：
timeout (int)是秒还是毫秒？负值是否禁用？插件不猜业务逻辑 - 异常说明：
Raises:段落完全空白，得自己加ValueError或ConnectionError - 示例代码块：
Examples:段落默认不出现，需手动开启autoDocstring.includeExamples并补内容
最易被忽略的一点：插件生成的是模板，不是终稿。它省掉的是格式排版和字段罗列，不是思考过程。参数含义、边界条件、副作用，这些永远得人来定。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
