Skip to content

Enforce docstring-presence rules incrementally (D100–D107) #1196

Description

@dgarros

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:

  1. 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.
  2. Peel off directories as they get documented; each PR shrinks the per-file-ignore list.
  3. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    effort/highThis issue should be completed in more than a daytype/tech-debtItem we know we need to improve way it is implemented

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions