Docstring coverage

Audited 2026-09-11 against checkout bf8804f plus this documentation change.

Recent automated review findings¶

The warnings are from CodeRabbit, not pytest coverage or a locally configured Python linter. The latest walkthrough comments retrieved during this audit say:

All require 80%. The current #93 comment supersedes an earlier recorded 24.32% / 37-function result. These are mutable comments: their update timestamps are not proof of the exact source revision evaluated. They do not publish a checker version, evaluation base/head pair, or function-by-function inventory. The local measurements below therefore do not reproduce or replace these bot results. A new CodeRabbit review on a published head is needed to verify its current diff-specific gate; no review was requested or PR posted in this audit.

CodeRabbit documents its check as applying to functions touched by the diff. This explains why documentation of test helpers and script adapters matters in addition to library APIs. CodeRabbit pre-merge checks

The initial audit preceded integration of PR #95. The PR branch now includes upstream 20240e2, and signal_metric documents multi-source means, per-source results, and optional permutation alignment. Its executable AST matches upstream. The follow-up validation passed 54 affected tests and all three coverage gates; the package totals below remain unchanged.

Reproduced local results¶

Both third-party tools were run from an isolated environment with pinned versions. The baseline was reconstructed from tracked Python files at bf8804f.

Scope is all 78 Python files under versa/, including the bundled NISQA, NORESQA, and PAM implementations. No paths, private functions, constructors, nested functions, or magic methods were excluded to reach the target. Setter and deleter checks are explicitly enabled for docstr-coverage. Tests and scripts are outside these package totals, but the missing function docstrings in files associated with #93 and #96 were also addressed.

For an additional local inventory, the current versions of the 33 Python files changed between caf9cbe and bf8804f (#96) have 328/328 documented functions. The eight Python files changed by merge caf9cbe relative to its first parent (#93) have 122/122. These count every current function in those files, not only changed functions; deleted definitions are absent. They are deliberately not labeled as reproductions of CodeRabbit's 72- and 41-function denominators.

The package gained 393 literal docstrings, including 335 function docstrings. The differing totals come from checker semantics: Interrogate counts empty modules, while docstr-coverage omits them. Four previously empty package initializers now contain documentation, increasing the latter denominator.

The third-party measurements used Python 3.14; regression tests used Python 3.12. CI runs the static checks on Python 3.10 without installing model dependencies.

What to document¶

Prioritize the contract a caller cannot infer from a function name:

• Metric compute methods: waveform axes, channel selection/mixing, sample-rate defaults, alignment, required references/text, output keys and units, numerical limitations, and errors. Examples: MAPSS source order and diagnostic artifacts; LogWMSE's configured model rate; WER edit counts versus normalized error rates.
• Setup and cache helpers: optional dependencies, downloads, device selection, global cache changes, and local/offline asset behavior.
• Scoring and reporting: file ownership, append/resume behavior, dispatch, missing/nonfinite values, score-direction heuristics, and report overwrites.
• Registry/discovery: metadata extraction without model imports, aliases, configuration inspection, and lazy runtime loading.
• Tests and adapters: the invariant asserted, fake backend behavior, or the compatibility contract being preserved. Short summaries are sufficient here.

The remaining missing functions are in bundled model internals; the AST check prints their exact file, line, and qualified name. Coverage establishes presence, not correctness or completeness. Review the documentation alongside the code.

Checker survey and selection¶

A relevant 2.3.2 implementation quirk: docstr-coverage's --skip-class-def uses name capitalization rather than the AST node type, and --skip-file-doc can still count documented modules. Those options changed the denominator during this audit and were not used as a true function-only gate. The small AST counter avoids that ambiguity. See the pinned implementation's node filtering and module collection logic.

Repeat the checks¶

Run from the repository root in a Python environment:

python -m pip install -r ci/requirements-docstrings.txt
interrogate --verbose --verbose --fail-under 80 versa
docstr-coverage --include-setter --include-deleter --fail-under 80 versa
python ci/check_function_docstrings.py --fail-under 80 versa

All three commands fail below 80%. The workflow runs both cross-checks even if the first check fails, so their missing-definition reports remain visible. The AST counter also accepts individual Python files or directories for a focused inventory, but it is not a reproduction of CodeRabbit's diff selection.

Validation: 118 tests passed across the regression selection and counter/cache checks, with one optional real-model test skipped. The new counter has tests for nested/async/private/init counting, exact threshold behavior, and empty-input rejection. All 177 tracked Python files passed Black; blocking Flake8 checks and git diff --check passed. Executable ASTs of all 74 existing modified Python files were compared with HEAD after removing only literal docstrings; scoring, signatures, and test behavior are unchanged.