Pydoclint 文档签名一致性校验器

你要解决什么问题

Python 的类型检查器（mypy、pyright）会在函数签名被改动时立刻报错，但文档字符串完全游离在这套保障之外。你把 update_user(user_id, *, verbose=False) 加上一个必填参数 reason，顺手在 docstring 里忘了写；或者删掉了 raises ValueError 那一节却没同步到文档。这类问题在 CI 里通常不会被捕获——测试用例大多按新签名调用，旧文档只是静静躺在代码里，直到有新人照着 Args: 清单写出一段必崩的调用。

这个技能如何工作

它把 pydoclint 接进你的工作流，对源码树执行自动化审查，核心检查三件事：

• 参数一致性：docstring 的 Args: 段落必须与函数签名逐一对应，多写、漏写、顺序错乱都会报错；
• 返回值一致性：声明了 Returns: 的函数，其文档描述的返回结构应与 return 语句实际产出的类型匹配；
• 异常一致性：函数抛出的异常是否都在文档的 Raises: 段落中被声明。

关键步骤很轻量：指定待检查的源码路径，工具会解析 AST、提取每个函数的 docstring 并做结构化比对，输出精确到行列号的差异清单。它支持 Google 与 NumPy 两种主流 docstring 风格，可以直接挂到 flake8 工作流里，让文档检查像 lint 代码一样成为合入前的硬门槛。

适用边界与注意点

• 它只做结构一致性校验，不会判断文档描述的业务逻辑是否正确；
• 对动态构造参数、装饰器大量改写签名的代码，可能产生误报，需要结合 noqa 或配置豁免；
• docstring 风格需在项目中统一，混用 Google 与 NumPy 格式会让比对结果不稳定；
• 它替代不了对 API 设计的评审，但能保证「代码改了什么，文档就说什么」。