Python函数文档自动生成依赖三重双引号包围的规范docstring，主流工具仅识别"""..."""格式；推荐Google/NumPy风格，需明确标注Args、Returns、Raises等字段。
Python函数文档自动生成依赖规范的docstring写法，主流工具（如Sphinx、pdoc、pydoc）都按约定格式解析，不按规范写，生成的文档会缺失参数、返回值或格式混乱。
必须使用三重双引号包围docstring
单引号、三重单引号或非三重字符串均不被标准工具识别。函数定义后紧接的字符串必须是red">"""..."""，且顶格或与def对齐（推荐顶格）。
- ✅ 正确：
def add(a, b):<br> """Return the sum of a and b."""<br> return a + b
- ❌ 错误：
def add(a, b):<br> 'Return the sum of a and b.' # 单引号不解析<br> return a + b
推荐采用Google或NumPy风格（非reStructuredText原生语法）
Sphinx配合sphinx.ext.napoleon插件可自动转换Google/NumPy风格为HTML文档，比纯reST更易读、少出错。核心字段需明确标注：
- Args: 每个参数占一行，格式为name (type): description，类型可省略但建议保留
- Returns: 写明返回值类型和含义，多返回值用括号说明，如(int, str)
- Raises: 列出可能抛出的异常及触发条件
示例：
立即学习“Python免费学习笔记（深入）”；
def fetch_user(user_id: int) -> dict:<br> """Retrieve user data by ID.<br><br> Args:<br> user_id (int): Unique identifier for the user.<br><br> Returns:<br> dict: User profile with keys 'name', 'email', and 'active'.<br><br> Raises:<br> ValueError: If user_id is negative.<br> ConnectionError: If backend service is unreachable.<br> """<br> if user_id < 0:<br> raise ValueError("user_id must be non-negative")<br> # ...函数签名与docstring参数必须严格一致
参数名拼写、顺序、是否带默认值，都要和def行完全匹配。工具不会做模糊匹配或推断。
- 若函数定义为def process(items: list, /, prefix: str = "v1")，docstring中Args:就必须分两行写清位置参数items和仅限关键字参数prefix，并注明默认值
- 省略prefix或写成pre会导致该参数在生成文档中消失
避免空行割裂、保持语义连贯
docstring首行是简短摘要（一句话），之后空一行再写详细说明。字段块（Args/Returns等）之间不加空行，字段内部可换行但不要空行隔开。
- ✅ 首行摘要 + 空行 + 详细说明 + 字段块（紧凑排列）
- ❌ 在Args和Returns之间插入空行，部分工具会截断后续内容
