Python函数docstring自动校验需统一格式、覆盖参数Args、返回值Returns、异常Raises三要素，并与类型标注双向对齐；推荐pydocstyle+darglint双工具协同校验，集成至pre-commit和CI强制执行。
Python函数文档字符串（docstring）的自动校验，核心在于统一格式、覆盖关键要素、并与代码行为保持一致。光写docstring不够，得让它可被工具读取、验证、甚至驱动测试或API生成。
必须包含的三个基础字段
按Google或NumPy风格，每个函数docstring至少应明确说明：参数类型与含义、返回值类型与语义、可能抛出的异常。缺失任一字段，校验即视为不通过。
-
Args: 每个参数单独一行，格式为
name (type): description，例如data (list[str]): 待处理的非空字符串列表 -
Returns: 明确写出类型和业务含义，如
str: 清洗后的首字母大写字符串，空输入返回空字符串 -
Raises: 只列实际会抛出的异常，如
ValueError: 当data包含None元素时触发，不写“可能出错”这类模糊描述
用pydocstyle + darglint组合校验
单一工具无法覆盖全部规范，推荐双工具协同：
-
pydocstyle 检查格式合规性：是否缺Summary、缩进是否统一、空行位置是否正确。运行命令：
pydocstyle --convention=google my_module.py -
darglint 深度校验内容一致性：参数是否在Args中声明、是否多写/漏写、类型标注与docstring是否冲突。启用严格模式：
darglint -v2 my_module.py - 二者结果需同时通过才算合格；任一报错都需人工确认——不是忽略警告，而是修正代码或docstring
类型标注与docstring必须双向对齐
Python 3.6+ 支持函数签名类型标注（如def func(x: int) -> str:），此时docstring中的Args和Returns必须与之完全一致，否则校验失败。
立即学习“Python免费学习笔记（深入）”；
- 若签名已写
x: Optional[str]，docstring中就不能只写x (str)，而应写x (Optional[str]): ... - 若返回值是
Union[int, None]，docstring中Returns字段必须体现可为空，例如int or None: 计算结果，失败时返回None - 工具如darglint默认开启类型对齐检查，无需额外配置
自动化集成到开发流程
避免靠人眼检查，把校验嵌入本地提交前和CI流水线：
- 用
pre-commit钩子自动运行：repos: - repo: https://github.com/PyCQA/pydocstyle ...，保存文件即提示错误 - GitHub Actions中添加步骤：
- name: Check docstrings; run: pip install pydocstyle darglint && pydocstyle . && darglint -v2 . - 建议设置为CI失败项（而非警告），强制团队遵守——文档即契约，不可妥协
不复杂但容易忽略：校验不是为了凑满字段，而是确保每个字都经得起推敲。函数改了逻辑，docstring没同步更新，那比没写还危险。
