DEV Community

Alberto Nieto
Alberto Nieto

Posted on • Originally published at alberto.codes

Your docstrings are lying — docvet 1.14 catches them

#python #documentation #ai #developertools

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

That's the gap docvet fills. And with v1.14, it closes the gap further — checking not just whether your docstrings exist, but whether they match your code.

What Changed

Parameter Agreement Checks

Two new rules — missing-param-in-docstring and extra-param-in-docstring — compare function signatures against Args: sections, parameter by parameter.

You know the drill: you rename retries to max_retries across a refactor, update every call site, and forget the docstring. Now docvet catches it:

src/client.py:47: missing-param-in-docstring Function 'connect' has parameters not documented in Args: max_retries [required]
Enter fullscreen mode Exit fullscreen mode

Handles positional-only params (PEP 570), keyword-only, self/cls exclusion, and both Google and Sphinx styles.

Reverse Enrichment Checks

Before 1.14, docvet asked "did the docstring mention this behavior?" Now it also asks the reverse: "does the docstring claim behavior the code doesn't exhibit?"

Three new rules:

  • extra-raises-in-docstring — documents exceptions the function never raises
  • extra-yields-in-docstring — documents yields in a non-generator
  • extra-returns-in-docstring — documents returns the function never makes

A docstring that claims FileNotFoundError when the function never raises anything is a trap. Callers write try/except blocks for phantom exceptions. AI tools generate defensive code for errors that can't happen.

Trivial Docstring Detection 

def get_user():
    """Get user."""
Enter fullscreen mode Exit fullscreen mode

This passes every presence check but adds zero information. The trivial-docstring rule decomposes symbol names and summaries into word sets, filters stop words, and flags cases where the summary is just an echo of the name.

Also in This Release

  • 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 with no type when there's no return annotation
  • undocumented-init-params (opt-in) — catches __init__ methods with parameters but no Args: section

Design note: Reverse checks use recommended severity (not required) to account for delegation patterns. Two rules are opt-in for progressive adoption. Full design tradeoffs in the blog post.

Getting Started 

pip install docvet==1.14.1
Enter fullscreen mode Exit fullscreen mode

Param agreement and reverse checks are on by default. Opt-in rules:

[tool.docvet.enrichment]
require-return-type = true
require-init-params = true
Enter fullscreen mode Exit fullscreen mode

Run it:

docvet check src/ --all --verbose
Enter fullscreen mode Exit fullscreen mode

What's Next

  • Semantic verification — not just "did you document the parameters?" but "is what you said about them accurate?"
  • Expanding multi-style support across all rule categories

PyPI | Docs | GitHub

Top comments (0)