docs: enforce public docstring coverage via ruff D1 and backfill#22
Merged
Conversation
Enable Ruff's public pydocstyle rules and exempt tests plus constructor and magic-method boilerplate. Backfill package contracts and document the gate so new public APIs cannot regress. Interrogate public docstring coverage: 49.3% before, 97.4% after. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
jeqcho
added a commit
that referenced
this pull request
Jul 14, 2026
Follow-up to #22, which added the ruff D1 public-docstring gate. Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds Ruff's pydocstyle presence rules (
D1) to the lint gate so every public module, class, and function must carry a docstring, and backfills the 32 that were missing. Public docstring coverage (interrogate at the merge-base, excluding private/nested/init): 56.4% -> 97.4%; the residual gap is only the deliberately exempted magic methods (D105) and__init__(D107, covered by class docstrings). Tests are exempt via per-file-ignores.Docstrings follow the repo's existing voice: they state the contract or role ("Draw by index so mixed-category scalar types are preserved.") rather than restating the symbol name.
The requirement is documented for contributors in CLAUDE.md's gates bullet and the README Development section.
Why
With external PRs picking up, the gate makes new public API arrive documented, the same way the 100% test-coverage gate makes it arrive tested. Ruff reports the exact undocumented symbol at its line, so contributors get actionable feedback with no new tooling.
Verification
All gates green locally: ruff check, ruff format, strict mypy, pytest at 100% coverage (317 passed), and
mkdocs build --strict(docstrings feed no API pages here yet, but the build stays clean).Implemented by Codex (GPT), reviewed by Fable.
🤖 Generated with Claude Code