docs: resolve docs-audit improvements P1–P25 + source-side notes, archive findings#72
Merged
Merged
Conversation
Closes the open tail of the 2026-06-12 docs audit (bugs B1–B14 shipped in #63, inaccuracies I1–I22 in #64; this is the improvements + source-side remainder). Every source-referenced claim was verified against the code. Docs (P1–P25): - index.md: sync the on-page index with mkdocs nav (tutorials, instrumentation seams, prometheus/otel setup, new Operations section). - installation.md: document the `all` extra. - how-it-works.md: self-contained DLQ snippet; retarget "Relay tutorial" link to the actual tutorial. - basic.md: say to save the module as app.py. - tutorials: schema-validation "what's next" pointer; `faststream[cli,kafka]`. - relay.md: import OutboxMessage alias; document the unstarted-foreign-broker WARNING + fail-and-retry safety net; correct the _OutboxConfigError row fate (lease-expiry retry, not retry_strategy); fix the misplaced NotImplementedError comment. - timers.md: timer_id dedups only live rows (partial index); fix the undefined-`order` snippet. - subscriber.md: document multi-queue subscribers + connection budget + same-queue competition; MANUAL silent-return = terminal reject warning. - publisher.md: "publisher's" not "decorator's" static headers; make the chained example coherent (FastAPI-context session note, no undefined symbols); duplicate-delivery-on-crash caveat. - fastapi.md: document dlq_table/metrics_recorder/routers not exposed on OutboxRouter (no router workaround); clarify "fresh session per delivery"; self-contained quickstart stubs. - schema-validation.md + alembic.md: compare_server_default=False caveat (a green validate_schema does not prove server defaults exist). - observability.md: `sum by (destination)` on per-queue PromQL; correct the `fetched` footnote (skipped when inflight full; first-queue tag only). - checklist.md: real ExponentialRetry kwarg names (the shorthand raised TypeError if copied). Source-side docstring/comment fixes (no logic change): - testing.py: "list of _FakeRow records" not "list of dicts"; fix the `test_broker.fake_client.dlq_rows` accessor comment; correct the TestOutboxBroker docstring (future-dated rows fire immediately in sync mode — it contradicted the already-correct module docstring). - publisher/usecase.py: de-duplicate the _REJECT_RELAY_MSG wording. Verified: mkdocs build --strict clean (all links/anchors resolve); lint-ci clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jun 13, 2026
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
The open tail of the 2026-06-12 docs audit. Bugs B1–B14 (#63) and inaccuracies I1–I22 (#64) already shipped; this PR resolves the remaining 25 improvements (P1–P25) plus the 4 source-side docstring/comment notes, then archives the findings doc as fully shipped.
Every source-referenced claim was re-verified against the code before writing.
Highlights
orderin timers,OrderIn/Orderin fastapi, the chained-publishing session block);checklist.mdretry kwargs were shorthand that doesn't exist (initial=/max=/…) and wouldTypeErrorif copied — now the realExponentialRetry(initial_delay_seconds=…, …)._OutboxConfigErrorrow fate (lease-expiry retry, notretry_strategy); the unstarted-foreign-broker WARNING + fail-and-retry safety net;timer_iddedups only live rows; MANUAL silent-return = terminal reject;compare_server_default=Falsemeans a greenvalidate_schema()doesn't prove server defaults exist; thefetchedmetric footnote.OutboxRouterdoesn't exposedlq_table/metrics_recorder/routersand there's no router workaround (documented, not papered over — forwarding them would be a separate feature).allextra, multi-queue subscribers, duplicate-delivery-on-crash caveat for chains.testing.pydocstrings/comments (incl. a class docstring that contradicted the module docstring on sync-mode timer firing);_REJECT_RELAY_MSGwording.Verification
mkdocs build --strict— clean (all internal links/anchors resolve).just lint-ci— clean.A follow-up commit archives
planning/active/2026-06-12-docs-audit-findings.md→archived/(status: shipped).🤖 Generated with Claude Code