Docstrings: the migrations API, PassReport and the CLI commands #721

src/ferro/pass_report.py — PassReport, ExecutedStatement, Report, Subject

• Kind: reference
• Verdict: compact, and ExecutedStatement documents each field properly. Elsewhere, field meanings sit in prose and the role values are never listed. B

src/ferro/migrations/ core — up, require_applied, status, check, baseline, remove_baseline, drift, render_op, step declarations, errors, BaselineReport, DriftReport, RunReport, HistoricalModels

• Kind: reference, written as dense specification prose
• Running example: author.slug backfill (chunked, todo) — consistent with the guides
• Verdict: precise and refusal-aware, but these docstrings are hard to scan. No function has an Args: table. Summaries run over two to three lines. 28 Sphinx roles render as literal text. up()'s return type is never documented on the page. C

src/ferro/migrations/testing.py — harness, Harness, RoundTripResult

• Kind: reference
• Running example: 0011/0012 slug backfill with Author (I-8 ✓)
• Verdict: the best in scope. Each method states its precondition and what is refused, with small checkable values. The rich example lives in the module docstring, which the page does not render. B

src/ferro/migrations/alembic.py — get_metadata, ferro_options, render_item

• Kind: reference
• Verdict: accurate, and ferro_options leads with the env.py snippet the reader needs. It reads more like explanation than reference in places. B

src/ferro/cli/ — main, render_refusal, Global, and ferro migrate <verb> --help

• Kind: reference (help text)
• Verdict: the verb summaries are the most consistent prose in scope: all infinitive, one line, and exit codes stated (check 0/3, status 0/3/4, drift 0/4). One rendering defect wipes out the placeholder in seven help strings. C (B once the H is fixed)

Cross-cutting patterns

1. Sphinx/RST markup inside Google docstrings (193 roles in in-scope modules; 43 render literally on the API pages in scope, plus :: markers in 8 places). :class:X``,:func:,`:meth:`,`:data:`show as literal text, and the targets are often unrendered (`InheritedEvent`,`StepEvent`,`AllowAhead`,`RouteHandle`). One mechanical pass to mkdocstrings autorefs (`[X][ferro.X]`) and fenced code fixes every case. Add a lint (`ruff` cannot catch this; a grep in CI can).
2. Parameters described in prose, not Args: (≈60 undocumented parameters across 25 functions). This affects the whole migrations API, the raw functions (sql, *args, using, session), the settings methods and Field (db_type, db_check, reverse_index). The API page then has no parameter table, and defaults are buried mid-paragraph.
3. Undocumented dataclass/pydantic fields (≈45 of the 54 missing docstrings). Affected: PoolConfig, DatabaseSettings, Session, Report, Subject, PassReport, Check, RowSecurity and the exception attributes. ExecutedStatement, RunReport and RoundTripResult already show the fix, a """…""" under each field.
4. Multi-line summaries (31 of 65 functions, 9 classes). The summary line ends mid-clause ("…, under" / "the run lock"). Rule 21 wants one line ending with a period.
5. Verb form: infinitive (46) vs noun phrase (18), never third-person. The project has in effect chosen infinitives. The 18 value-returning methods written as noun phrases are the outliers to convert. Exceptions use three different opening forms.
6. Internals and project history in public docstrings (18 ADR/issue refs, plus registry/Rust/ContextVar mechanics). Affected: clear_registry, ensure_resolved_modelset, create_tables, raw.execute, FerroSettings, render_item. Readers cannot follow ADR-0056 or #443, and "pushes the SchemaIR to the Rust runtime" answers no user question (I-11).
7. Explanation essays in reference entries (PoolConfig ~90 lines, Session.set_config 68 lines, connect 96 lines). The content is good, but it belongs in the RLS/connections guides with a link (rule 1). set_config even sends readers to the source.
8. Silent rendering breakage griffe never warns about (3 places + 1 CLI-wide). Unindented Returns: continuations split into 2 and 5 table rows (create_tables, migrate). Types sit inside the Returns description (current_session). Markdown help rendering erases <placeholders> from seven CLI help strings. Running griffe for warnings alone is not a sufficient gate; a test that renders the pages and greps for :class:, repeated return rows and empty placeholders would catch all three.