Docstring Argument Coverage Checker

A utility that scans Python modules to ensure every parameter in public callables is documented in the argument section of their docstrings for Google, NumPy, or Sphinx conventions.

Capabilities

Reports undocumented parameters

• Given a file containing a Google-style docstring where parameter bar is missing from the Args list, the check reports bar as undocumented for that function and returns a non-zero exit indicator. @test

Supports multiple docstring conventions

• When run against a NumPy-style docstring whose Parameters section documents every argument, the check completes with zero undocumented parameters and a zero exit indicator. @test
• For a Sphinx-style docstring that omits the timeout parameter, the check reports exactly that missing parameter and includes its line number. @test

Skips non-required parameters

• Parameters named self or cls are not treated as undocumented even if absent from the docstring sections. @test

Implementation

@generates

API

from __future__ import annotations
from typing import Iterable, Literal, TypedDict, List

Docstyle = Literal["google", "numpy", "sphinx"]

class UndocumentedParam(TypedDict):
    path: str
    object: str
    argument: str
    line: int
    source: str | None

class CoverageReport(TypedDict):
    files_scanned: int
    undocumented: List[UndocumentedParam]
    exit_code: int

def check_argument_docs(paths: Iterable[str], style: Docstyle, *, include_source: bool = False) -> CoverageReport:
    """Analyze Python files and report parameters missing from docstring argument sections."""

def main(argv: list[str] | None = None) -> int:
    """CLI entry point that prints a human-readable report and returns the exit code."""

Dependencies { .dependencies }

pydocstyle { .dependency }

Docstring style linter used to parse Google, NumPy, and Sphinx docstring sections and detect undocumented parameters.