Python 文档字符串检查器

为什么需要文档字符串检查

当团队协作或长期维护 Python 项目时，文档字符串的格式混乱会导致三个典型问题：类型标注与文档脱节，例如 def calc(x: int) -> str 的参数说明缺失类型解释；多风格混用，NumPy 风格的参数表格与 Google 风格的字段说明在同一文件中交替出现；关键信息缺失，返回值、异常、示例等 PEP 257 要求的模块级或函数级文档未覆盖。这些不一致不仅增加阅读成本，还会让自动化工具（如类型检查器、文档生成器）的输出失去可靠性。

这个技能如何解决问题

该技能通过 AST 解析 与 pydocstyle 规则引擎 的组合实现双重保障。核心能力包括：

• 格式识别与校验：自动检测 NumPy、Google、Sphinx 三种主流文档字符串格式，根据 pydocstyle 的约定规则（如 D203/D213 等）检查行宽、段落结构、首行摘要等细节
• 动态生成补全：当检测到缺失的文档字符串时，基于函数签名、类型标注和上下文逻辑自动生成符合 PEP 257 的模块/类/方法文档框架
• 类型桩集成：通过 .pyi 文件中的类型信息补充文档中的参数类型说明，确保 __annotations__ 与实际文档一致

关键工作步骤分为三步：

1. 使用 ast.parse() 解析源代码，提取函数/类/模块的文档字符串原始内容
2. 运行 pydocstyle 的 linter 规则集，输出格式错误、缺失字段、风格冲突等问题清单
3. 针对缺失的文档字符串，调用内置模板引擎生成包含参数、返回值、异常说明的初始文档框架

适用边界与注意事项

该技能的核心依赖是 pydocstyle 的静态分析能力，因此存在三个明确边界：

• 不支持动态生成的文档：对于通过 __doc__ = ... 动态赋值或装饰器生成的文档字符串，无法准确提取和校验
• 复杂格式需手动调整：虽然支持 NumPy/Google/Sphinx 格式，但涉及嵌套结构、自定义指令（如 Sphinx 的 .. seealso::）时，自动生成的内容可能需要人工二次编辑
• 与类型检查器互补：类型桩集成功能需要与 mypy/pyright 等工具配合使用，单独运行无法验证运行时类型一致性

实际使用中建议：

• 优先在 CI/CD 流水线 中集成该技能，作为提交前检查的强制环节
• 对于已有项目，可先通过 pydocstyle --select=D 运行全量检查，再逐步修复高优先级规则（如 D100/D101）对应的问题
• 类型桩文件（.pyi）的更新需要与文档字符串同步，避免因类型信息过时导致生成内容失真

总结：这个技能通过标准化检查和自动化生成，解决了 Python 文档字符串的三大一致性问题。它的价值不在于替代人工文档编写，而在于在代码变更时强制保持文档与代码的同步更新，减少因文档滞后导致的维护成本。