docstring 是文档生成工具的唯一数据源，必须紧贴函数定义、顶格书写、用三引号包裹，并遵循 Google/Numpy 等标准格式，否则会导致文档空白、参数缺失、doctest 失效及 IDE 提示不全。
docstring 是 Sphinx、pdoc 等工具的唯一数据源
这些工具不会解析注释、类型提示或变量名，只读取 __doc__ 属性值。如果函数没有 docstring，或写在错误位置（比如缩进后、代码之后），__doc__ 就是 None，生成的文档里对应条目直接空白。
常见错误现象：
- 运行
sphinx-build docs _build后页面中函数描述为空 -
pdoc your_module输出里参数列表缺失，只有签名 -
help(your_function)打印出None
实操建议：
- docstring 必须紧贴函数定义下一行，顶格写，不能缩进
- 必须用三引号（
"""或'''），单双引号不行 - 不要在 docstring 前加空行，也不要在函数体第一行代码前插其他语句
Google/Numpy/Sphinx 格式决定字段是否被提取
工具不是“读懂”文字，而是按格式规则做字符串匹配。比如 Sphinx 的 autodoc 插件默认只识别 Numpy 风格的 Parameters 和 Google 风格的 Args:，其他写法（如“参数说明：”）会被忽略。
示例对比：
def load_data(path: str) -> dict:
"""Load config from JSON file.
<pre class="brush:php;toolbar:false;">Args:
path (str): Path to the config file.
Returns:
dict: Parsed configuration.
"""
这段能被 Google 格式解析器正确提取参数和返回值；而下面这个：
def load_data(path: str) -> dict:
"""Load config from JSON file.
- path: Path to the config file.
- returns: Parsed configuration.
"""
所有字段都会被当成普通描述文本，不进入结构化字段。
实操建议：
- 选一种格式（推荐 Google 或 Numpy）并在团队内统一
- 用
autoDocstring插件自动生成，避免手误格式错位 - 检查生成结果时，重点看参数表、返回值、异常是否完整出现
doctest 依赖 docstring 中的代码块执行验证
如果 docstring 里写了 >>> 开头的交互式示例，但格式不标准（比如少空格、多缩进、没空行分隔），doctest.testmod() 就会跳过或报错，导致测试失效。
容易踩的坑：
- 示例末尾多了一个空格：
6vs6 - 预期输出和
>>>行之间没空行 - 用了中文引号或全角字符
实操建议：
- 用
python -m doctest your_module.py -v单独跑验证 - 避免在示例中使用依赖外部状态的代码（如
time.time()） - doctest 不是单元测试替代品，仅用于简单逻辑演示
IDE 提示和 LSP 补全是靠 docstring 内容渲染的
VS Code、PyCharm 的悬浮提示、参数补全，底层调用的是 Python 的 inspect.getdoc()，它返回的就是 __doc__。如果 docstring 缺失、为空或格式混乱（比如首行没句号、没空行分隔），提示就会截断或显示不全。
典型表现：
- 鼠标悬停时只显示第一行，后面参数说明消失
- 输入
func(后弹出的参数提示里类型和描述都是Any和空字符串
实操建议：
- 单行 docstring 一定要以句号结尾，否则部分 LSP 实现会截断
- 多行 docstring 第一行后必须空一行，再写详细说明
- 类型提示（
a: int）不能代替 docstring 中的参数描述，两者要共存
真正卡住自动化流程的，往往不是“没写 docstring”，而是“写了但不符合工具约定的格式边界”。一个空行、一个冒号、一个缩进，就可能让整个 API 文档生成链路掉一环。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
