From 8bd66bbe65e4ac5d508698fd455f9f36e8897765 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Wed, 6 May 2026 13:36:03 -0400 Subject: [PATCH] [F53 measurement] document protocol-crate missing-docs magnitude MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enabled #![warn(missing_docs)] on each of the 7 protocol crates to measure how many one-liners filling them in would be: mxaccess-asb 422 mxaccess-nmx 398 mxaccess-callback 371 mxaccess-galaxy 229 mxaccess-codec 205 mxaccess-rpc 147 mxaccess-asb-nettcp 111 ----- Total 1883 Reverted the lint enables — most of those are protocol-internal types (struct fields on wire-shape records, enum variants on opcode discriminators) whose meaning is already documented at the consumer-facing layer. Filling 1883 one-liners adds noise without consumer value, and forcing them as errors via RUSTDOCFLAGS would block routine cargo doc runs. design/followups.md F53 entry updated with the measured numbers and the explicit "stays off indefinitely" verdict. If a future contributor wants per-crate enforcement, the recipe in the strategy paragraph (allow(missing_docs) on protocol-internal modules, warn(missing_docs) on the re-export surface) is still valid. Co-Authored-By: Claude Opus 4.7 (1M context) --- design/followups.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/design/followups.md b/design/followups.md index 5bf3f24..48d675c 100644 --- a/design/followups.md +++ b/design/followups.md @@ -57,7 +57,20 @@ If this changes (e.g. internal consumer wants registry-style versioning via a pr **Resolves when:** all three optimisations land or are deliberately rejected with a note in the baseline doc. ### F53 — Enable `#![warn(missing_docs)]` workspace-wide -**Status:** Consumer crates resolved 2026-05-06: `#![warn(missing_docs)]` enabled on `mxaccess` and `mxaccess-compat` lib roots, every public item now carries at least a one-line doc comment, `RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps` clean. Protocol crates (`mxaccess-codec`, `mxaccess-rpc`, `mxaccess-galaxy`, `mxaccess-nmx`, `mxaccess-callback`, `mxaccess-asb`, `mxaccess-asb-nettcp`) deliberately deferred per the strategy paragraph below — their consumers (`mxaccess` + `mxaccess-compat`) already document the surfaces they re-export, and forcing one-liners on every transport-internal item adds noise without consumer value. +**Status:** Consumer crates resolved 2026-05-06: `#![warn(missing_docs)]` enabled on `mxaccess` and `mxaccess-compat` lib roots, every public item now carries at least a one-line doc comment, `RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps` clean. Protocol crates deliberately deferred per the strategy paragraph below — measured the magnitude on 2026-05-06 by enabling the lint on each: + +| Crate | Missing-docs warnings | +|---|---| +| `mxaccess-asb` | 422 | +| `mxaccess-nmx` | 398 | +| `mxaccess-callback` | 371 | +| `mxaccess-galaxy` | 229 | +| `mxaccess-codec` | 205 | +| `mxaccess-rpc` | 147 | +| `mxaccess-asb-nettcp` | 111 | +| **Total** | **1883** | + +Most of those are protocol-internal types (struct fields, enum variants on wire-shape records) whose meaning is already documented at the consumer-facing layer. Filling 1883 one-liners adds noise without consumer value, and turning them into errors (`RUSTDOCFLAGS="-D warnings"`) would block routine `cargo doc` runs. Lint stays off on protocol crates indefinitely; if a future contributor wants per-crate enforcement, they can re-introduce on a per-module basis with `#![allow(missing_docs)]` exemptions for the protocol-internal modules. **Severity:** P3 — doc-coverage tightening; not a correctness or release blocker. **Source:** F42 closeout — the missing-docs lint was deferred because enabling it surfaces hundreds of low-priority public-item gaps that are out of scope for that F-number.