Your docstrings are lying — docvet 1.14 catches them

Source: Dev.to

Overview

A 2024 study by Macke & Doyle found that incorrect documentation degrades LLM task success by 22.6 percentage points. Missing documentation had no statistically significant effect, meaning an AI coding assistant performs worse with wrong docs than with no docs at all.

Docvet bridges that gap. With v1.14 it not only checks that docstrings exist, but also verifies that they match the code.

Background

Docvet’s original focus was on presence checks—ensuring a docstring mentioned a behavior. Version 1.14 adds reverse checks: “does the docstring claim behavior the code doesn’t exhibit?”

What’s new in docvet 1.14

Parameter agreement

Two new rules compare function signatures against the Args: section, parameter by parameter:

• missing‑param‑in‑docstring – flags parameters present in the signature but absent from the docstring.
• extra‑param‑in‑docstring – flags parameters documented in Args: that are not in the signature.

Example

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

Docvet handles positional‑only parameters (PEP 570), keyword‑only parameters, and excludes self/cls. It supports both Google and Sphinx docstring styles.

Reverse behavior checks

Three new rules detect documentation that describes behavior the code never exhibits:

• extra‑raises‑in‑docstring – documents exceptions the function never raises.
• extra‑yields‑in‑docstring – documents yield statements in a non‑generator.
• extra‑returns‑in‑docstring – documents return values the function never produces.

Pitfall: A docstring claiming FileNotFoundError when the function never raises it leads callers to write unnecessary try/except blocks, and AI tools may generate defensive code for impossible errors.

Trivial docstring detection

The trivial‑docstring rule decomposes symbol names and summaries into word sets, filters stop words, and flags cases where the summary merely echoes the name.

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

This passes presence checks but adds no information.

Deprecation and return‑type checks (opt‑in)

• missing‑deprecation – catches warnings.warn(DeprecationWarning) or @deprecated (PEP 702) without a deprecation notice in the docstring.
• missing‑return‑type (opt‑in) – flags Returns: sections lacking a type when there’s no return annotation.
• undocumented‑init‑params (opt‑in) – catches __init__ methods with parameters but no Args: section.

Design notes

• Reverse checks use a recommended severity (not required) to accommodate delegation patterns.
• The opt‑in rules allow progressive adoption. Full design trade‑offs are discussed in the accompanying blog post.

Installation

pip install docvet==1.14.1

Configuration (opt‑in rules)

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

Usage

docvet check src/ --all --verbose

Docvet now performs semantic verification—not just “did you document the parameters?” but “is what you said about them accurate?” It also expands multi‑style support across all rule categories.

Further reading

• PyPI
• Docs
• GitHub