From f0c908d5fdc2d4656595a6cd95efaed81094d82b Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 9 Nov 2026 09:40:40 -0800 Subject: [PATCH 1/2] quest: plan the doc(hidden) ban Co-Authored-By: Claude Opus 5.5 --- quest/m2/api-shape/README.md | 1 + quest/m2/api-shape/doc-hidden.md | 52 ++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+) create mode 100644 quest/m2/api-shape/doc-hidden.md diff --git a/quest/m2/api-shape/README.md b/quest/m2/api-shape/README.md index c32ca6acaf8..fec23e5b9cd 100644 --- a/quest/m2/api-shape/README.md +++ b/quest/m2/api-shape/README.md @@ -61,3 +61,4 @@ Rejected in planning: - [moq-net's route stream goes public](/quest/m2/api-shape/net.md) - un-hide `origin::Consumer::routes` and reshape `RouteEvent`, now that #8063 merged - [JS Key.sign takes exactly Claims](/quest/m2/api-shape/auth-sign.md) - `@moq/auth` signs only `Claims`, with no legacy `put`/`get` input, like Rust +- [Ban doc(hidden) in Rust](/quest/m2/api-shape/doc-hidden.md) - `just check` bans it; each use becomes private or documented, test-support modules documented behind their feature diff --git a/quest/m2/api-shape/doc-hidden.md b/quest/m2/api-shape/doc-hidden.md new file mode 100644 index 00000000000..fc90daa11f4 --- /dev/null +++ b/quest/m2/api-shape/doc-hidden.md @@ -0,0 +1,52 @@ +# [M] Ban doc(hidden) in Rust + +## Goal + +`just check` fails on any `#[doc(hidden)]` in the repository's Rust, vendored +code included. Each current use becomes private (`pub(crate)` or narrower), or +documented public API. A public item is either documented or not public. + +JS `@internal` is out of scope: it is how a JS package shares code across its +own modules without publishing it, which TypeScript has no visibility for. + +## Plan + +Planned 2026-11-09 (maintainer, /quest-complete follow-up of +[moq-dev/moq#8369](https://github.com/moq-dev/moq/pull/8369), which un-hid +moq-net's route stream: "audit any other doc(hidden). In fact just ban it"). + +Decisions: + +- ✅ The ban covers `rs/moq-webrtc/src/vendor` too (rejected: exclude vendored + code). Those modules are private and already trimmed by hand, so their + `doc(hidden)` hides nothing and can be deleted; record the change wherever + `vendor/mod.rs` tracks local edits. +- ✅ Feature-gated test support stays `pub` behind its feature and is + documented, like tokio's `test-util` (rejected: make it private by moving + bench and fuzz bodies into the crate). This covers `pub mod fuzz` (moq-net, + moq-quic, moq-mux, moq-rtmp), `pub mod sim` (moq-quic, moq-tokio, and + `quic::driver::sim`), and the bench exports (`moq_json::bench`, + `moq_stats::produce::bench`, `moq_quic::BenchSentPackets`). Each one's doc + line says it is test support and names the feature that enables it. +- ✅ Rust only (rejected: audit or ban JS `@internal`). +- ✅ m2, in this epic (rejected: m3 with the audits). + +Guidance for the rest: `moq_tokio::settings` (used by moq-relay and +moq-bench), `moq_quic::mux` and its `connection::mux` re-export, and +`moq_webrtc::p2p` follow this epic's rules: private when only the crate uses +it, deleted when nothing does, otherwise documented. The two hides on moq-net's +route stream go with #8369. + +Add the check where `just check` already scans tracked text (`sh/text.sh` +greps every tracked file for em dashes), so it runs in the merge gate. Update +[wire fuzz coverage](/quest/m4/wire-fuzz-coverage.md), which asks for a +"hidden `fuzz` module", and [the relay over QUIC on the sim](/quest/m4/quic-sim.md), +which describes moq-tokio's "hidden `sim` feature", to match. + +Public API: newly documented items in moq-net, moq-quic, moq-mux, moq-rtmp, +moq-json, moq-stats, moq-tokio, and moq-webrtc; anything made private or +deleted is breaking. Wire: none. + +## Related + +- [Lint audit](/quest/m3/audit-lints.md) - the wider lint configuration From aaff7fd1259e4167722c79db4077408b256c5a6a Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Mon, 9 Nov 2026 09:44:44 -0800 Subject: [PATCH 2/2] quest: fix the doc(hidden) plan's paths and tense BenchSentPackets is reached as moq_quic::connection::BenchSentPackets. #8369 is still open, so the plan says it un-hides the route stream. vendor/mod.rs records upstream revisions, not local edits. Co-Authored-By: Claude Haiku 5.5 --- quest/m2/api-shape/doc-hidden.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/quest/m2/api-shape/doc-hidden.md b/quest/m2/api-shape/doc-hidden.md index fc90daa11f4..706126273e0 100644 --- a/quest/m2/api-shape/doc-hidden.md +++ b/quest/m2/api-shape/doc-hidden.md @@ -12,21 +12,21 @@ own modules without publishing it, which TypeScript has no visibility for. ## Plan Planned 2026-11-09 (maintainer, /quest-complete follow-up of -[moq-dev/moq#8369](https://github.com/moq-dev/moq/pull/8369), which un-hid +[moq-dev/moq#8369](https://github.com/moq-dev/moq/pull/8369), which un-hides moq-net's route stream: "audit any other doc(hidden). In fact just ban it"). Decisions: - ✅ The ban covers `rs/moq-webrtc/src/vendor` too (rejected: exclude vendored code). Those modules are private and already trimmed by hand, so their - `doc(hidden)` hides nothing and can be deleted; record the change wherever - `vendor/mod.rs` tracks local edits. + `doc(hidden)` hides nothing and can be deleted. `vendor/mod.rs` records + upstream revisions, not local edits, so the removal needs no note there. - ✅ Feature-gated test support stays `pub` behind its feature and is documented, like tokio's `test-util` (rejected: make it private by moving bench and fuzz bodies into the crate). This covers `pub mod fuzz` (moq-net, moq-quic, moq-mux, moq-rtmp), `pub mod sim` (moq-quic, moq-tokio, and `quic::driver::sim`), and the bench exports (`moq_json::bench`, - `moq_stats::produce::bench`, `moq_quic::BenchSentPackets`). Each one's doc + `moq_stats::produce::bench`, `moq_quic::connection::BenchSentPackets`). Each one's doc line says it is test support and names the feature that enables it. - ✅ Rust only (rejected: audit or ban JS `@internal`). - ✅ m2, in this epic (rejected: m3 with the audits). @@ -35,7 +35,8 @@ Guidance for the rest: `moq_tokio::settings` (used by moq-relay and moq-bench), `moq_quic::mux` and its `connection::mux` re-export, and `moq_webrtc::p2p` follow this epic's rules: private when only the crate uses it, deleted when nothing does, otherwise documented. The two hides on moq-net's -route stream go with #8369. +route stream go with #8369; if it has not landed when this is worked, remove +them here. Add the check where `just check` already scans tracked text (`sh/text.sh` greps every tracked file for em dashes), so it runs in the merge gate. Update