你的 docstrings 在撒谎——docvet 1.14 捕捉它们

Source: Dev.to

概览

2024 年 Macke 与 Doyle 的研究发现，错误的文档会使 LLM 任务成功率下降 22.6 个百分点。缺失文档并未产生统计显著的影响，这意味着 AI 编码助手在面对错误文档时的表现甚至比没有文档时更差。

Docvet 弥补了这一缺口。使用 v1.14，它不仅检查是否存在 docstring，还验证它们是否 与代码匹配。

背景

Docvet 最初的重点是存在性检查——确保 docstring 提到了某个行为。版本 1.14 添加了 逆向 检查：“docstring 声称的行为在代码中并未出现吗？”

docvet 1.14 的新特性

参数一致性

两个新规则逐个比较函数签名与 Args: 部分的参数：

• missing‑param‑in‑doc-string – 标记签名中存在但在 docstring 中缺失的参数。
• extra‑param‑in‑doc-string – 标记在 Args: 中记录但签名中不存在的参数。

示例

src/client.py:47: missing‑param‑in‑doc-string
Function 'connect' has parameters not documented in Args: max_retries [required]

Docvet 能处理仅位置参数（PEP 570）、仅关键字参数，并会排除 self/cls。它支持 Google 与 Sphinx 两种 docstring 风格。

逆向行为检查

三个新规则检测文档中描述了代码从未出现的行为：

• extra‑raises‑in‑doc-string – 记录函数从未抛出的异常。
• extra‑yields‑in‑doc-string – 在非生成器函数中记录 yield 语句。
• extra‑returns‑in‑doc-string – 记录函数从未返回的返回值。

陷阱：如果 docstring 声称会抛出 FileNotFoundError，而函数实际上从不抛出，这会导致调用者编写不必要的 try/except 块，AI 工具也可能为不可能的错误生成防御性代码。

平凡 docstring 检测

trivial‑doc-string 规则将符号名称和摘要拆分为词集合，过滤停用词，并在摘要仅是名称的重复时标记。

def get_user():
    """Get user."""

这通过了存在性检查，却没有提供任何信息。

弃用与返回类型检查（可选）

• missing‑deprecation – 捕获 warnings.warn(DeprecationWarning) 或 @deprecated（PEP 702）但在 docstring 中缺少弃用说明的情况。
• missing‑return‑type（可选） – 当函数没有返回注解且 Returns: 部分缺少类型时标记。
• undocumented‑init‑params（可选） – 捕获 __init__ 方法有参数却没有 Args: 部分的情况。

设计说明

• 逆向检查使用推荐的严重程度（非强制），以适应委托模式。
• 可选规则允许逐步采用。完整的设计权衡在配套博客文章中有详细讨论。

安装

pip install docvet==1.14.1

配置（可选规则）

[tool.docvet.enrichment]
require-return-type = true
require-init-params = true

使用

docvet check src/ --all --verbose

Docvet 现在执行 语义验证——不仅是“你是否记录了参数？”而是“你对它们的描述是否准确？”它还在所有规则类别中扩展了多风格支持。

进一步阅读

• PyPI
• Docs
• GitHub