dohertj2/mxaccess
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[F53 measurement] document protocol-crate missing-docs magnitude
rust / build / test / clippy / fmt (push) Has been cancelled
Details
rust / cargo public-api drift check (F41) (push) Has been cancelled
Details

Browse Source 
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) <noreply@anthropic.com>
This commit is contained in:
Joseph Doherty
2026-05-06 13:36:03 -04:00
parent 349e217ea3
commit 8bd66bbe65
1 changed files with 14 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
design/followups.md
+14 -1
View File
@@ -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.