Why
Follow-up to #1184. The bulk of the docstring backlog is "missing docstring"
(presence) rules — ~2,275 violations. Unlike the consistency rules, these require
writing docstrings, so a big-bang is impractical. This issue tracks clearing
them incrementally, public API first, without blocking the whole rule set.
Goal: enforce presence rules on the public surface first, then peel off the rest,
so the parked list becomes a visible, shrinking to-do map.
Non-goals: the consistency rules (D417/DOC502/DOC201) — tracked in the Phase 1
step 2 issue.
Scope (currently parked)
| Code |
Rule |
Count |
| D102 |
undocumented-public-method |
705 |
| D103 |
undocumented-public-function |
632 |
| D101 |
undocumented-public-class |
536 |
| D100 |
undocumented-public-module |
217 |
| D107 |
undocumented-public-init |
91 |
| D104 |
undocumented-public-package |
55 |
| D105 |
undocumented-magic-method |
39 |
Total ≈ 2,275 violations.
Approach
Convert the global park into shrinking per-file-ignores rather than a single
global ignore:
- Enforce D101/D102/D103 on the public surface first —
client.py, node/,
config.py — and keep them parked only for tests/, ctl/, and internal modules.
- Peel off directories as they get documented; each PR shrinks the per-file-ignore list.
- Document lower-priority areas (magic methods D105,
__init__ D107, package
docstrings D104) last.
Consider splitting into per-area sub-issues once the public-API surface is done.
Done when
- D100–D107 are enforced repo-wide (no remaining per-file-ignores for them).
uv run ruff check is green.
Related
- Ratchet idea (separate future issue): a CI step running
ruff check --select D,DOC
on the diff only, so new code must be clean while the historical backlog is parked.
Why
Follow-up to #1184. The bulk of the docstring backlog is "missing docstring"
(presence) rules — ~2,275 violations. Unlike the consistency rules, these require
writing docstrings, so a big-bang is impractical. This issue tracks clearing
them incrementally, public API first, without blocking the whole rule set.
Goal: enforce presence rules on the public surface first, then peel off the rest,
so the parked list becomes a visible, shrinking to-do map.
Non-goals: the consistency rules (D417/DOC502/DOC201) — tracked in the Phase 1
step 2 issue.
Scope (currently parked)
Total ≈ 2,275 violations.
Approach
Convert the global park into shrinking
per-file-ignoresrather than a singleglobal ignore:
client.py,node/,config.py— and keep them parked only fortests/,ctl/, and internal modules.__init__D107, packagedocstrings D104) last.
Consider splitting into per-area sub-issues once the public-API surface is done.
Done when
uv run ruff checkis green.Related
ruff check --select D,DOCon the diff only, so new code must be clean while the historical backlog is parked.