alkhttp/tasks/infra/review-001-missing-docs-sweep.md

---
id: review-001-missing-docs-sweep
name: missing_docs sweep + publish-prep decisions (HY-02, HY-04, HY-11)
status: completed
depends_on: [review-001-client-config-and-cert-coverage]
scope: moderate
risk: low
impact: project
level: implementation
tags: [infra, review-001, docs, publish-prep]
---

## Description

The pre-crates.io documentation gate, deferred through the remediation
cycle so the API could stabilize first (it now has):

- **HY-02 [major]**: ~104 missing-docs warnings under
  `RUSTDOCFLAGS="-W missing_docs" cargo doc --no-deps` (was 110 at
  review time; the re-measure is current). Worst offenders were
  `openapi_spec.rs` (28), `http_client.rs` (28), `forward.rs` (10),
  `server/adapter.rs` (10), `dispatch.rs` (7), `routes.rs` (6); plus
  `gateway/mod.rs` / `server/mod.rs` module docs. Sweep and make the
  gate pass — better, enforce it (add `-D missing_docs` to
  `RUSTDOCFLAGS` in CI or a `#![deny(missing_docs)]`-style lint config
  the repo agrees on, so it cannot regress).
- **HY-11**: decide whether `docs/architecture/` (672 KiB) ships in the
  published package (the `exclude` list currently keeps it, omits
  `docs/reviews/`). If it ships, verify intra-doc links resolve on
  docs.rs; if not, confirm ADR references in rustdoc degrade acceptably.
  Record the decision in the task summary either way.
- **HY-04**: the `unwrap` inside shipped `test_support`
  (`websocket/upgrade.rs:161`, behind the opt-in `test-support` feature)
  is documented-as-intentional published API with a panic inside — make
  the final call: keep (document on the public item) or restructure to
  return `Result`.

Depends on the client task because `http_client.rs` is 28 of the
warnings and that task reshapes the config surface it would document.

## Acceptance Criteria

- [x] `cargo doc` with `-W missing_docs` (as deny) exits clean — 0 warnings
- [x] Enforcement landed (CI rustdocflags or lint config) so it stays clean
- [x] HY-11 decision recorded; `cargo publish --dry-run --allow-dirty` package contents match the decision
- [x] HY-04 resolved (documented or restructured)
- [x] `cargo test`, `cargo clippy --all-targets -- -D warnings`, `cargo fmt --check` pass

## References

- docs/reviews/001-initial-implementation-review.md (Part H, HY-02, HY-04, HY-11)

## Notes

Re-measure at start (after the three preceding follow-up tasks):
**101 warnings** across 16 files — the client task had already
documented its new surface, and OAI-06 grew `openapi_spec.rs`.
Sweep order followed the re-measure, not the review's ranking.

**HY-02 mechanics**: documented every public/`pub(crate)`-doc-visible
item across `openapi_spec.rs` (the document model: per-field meaning
+ OAI-06 key semantics), `forward.rs` (`HttpAuthScheme`,
`HttpServiceConfig`), `http_client.rs` (`HttpClientBuildError`
per-variant incl. `#[source]` fields, `SharedHttpClient`,
`client()`/`config()` accessors), `retry_after.rs` (the middleware +
`# Panics` on zero capacity), `dispatch.rs`, `error.rs`, `routes.rs`
(`CallRequest`/`SchemaQuery`/`SubscribeStream`), `server/adapter.rs`
(ALPNs, `HttpAdapter` + builders + accessors), `decoy.rs`,
`healthz.rs`, `state.rs` (incl. struct-variant fields),
`websocket/upgrade.rs` + `byte_adapter.rs` (`WsSessions`, `WsPumps`),
`from_openapi.rs`, `from_jsonschema.rs`, `from_mcp/mod.rs`,
`from_wss.rs`, `to_mcp.rs`, `lib.rs` (module docs + `#![deny]`).
The `deny(missing_docs)` at the crate root is the enforcement —
`cargo test` builds the `#[cfg(test)]` code too, so the gate covers
the `test-support` module's docs as well (rustdoc alone misses
those). Opportunistic HY-10 closure: all 8
`https://docs.rs/alkhttp (docs/architecture/decisions)` placeholder
links and the one relative `../docs/architecture/...` link converted
to plain-text ADR mentions — zero `cargo doc` warnings (including
`-D warnings`) now, versus 10 pre-existing private-link warnings
before.

**HY-11 decision recorded**: `docs/architecture/` does **not** ship.
- Rationale: the ADRs are contributor-facing design records (internal
  strategy, open questions, rejected designs), not user docs; shipping
  them publishes future-direction material to crates.io. The rustdoc
  ADR references degrade to plain text uniformly (see HY-10) — no
  half-resolved links, nothing dangling on docs.rs.
- Landed as `exclude = [".opencode/", "AGENTS.md", "docs/", "tasks/",
  "Cargo.lock"]`. Also excluded `tasks/` (42 task files, internal
  process material, same rationale as `docs/reviews/`' existing
  exclusion).
- `cargo publish --dry-run --allow-dirty` verified: **38 files,
  ~889 KiB** — `src/` (31) + 5 integration tests + manifest/lock/git-
  metadata. `cargo package --list` contains zero `docs/` or `tasks/`
  entries. (Tests ship intentionally — standard for crates; 112 KiB.)
- Note: `Cargo.lock` appears in the package despite the exclude entry —
  cargo ≥1.54 always packages it for libraries; harmless (crates.io
  ignores it) and the exclude entry documents intent.

**HY-04 decision recorded**: **keep + document**, not restructure.
`frame_channel0_chunk`'s `unwrap` is on `serde_json::to_vec` of the
acyclic `EventEnvelope` wire type (no non-string map keys, no untagged
ambiguities) — the failure mode is unreachable, and a `Result` return
would poison every test call site (this crate's + downstream
consumers') for an impossible case, which is worse ergonomics than a
documented panic. `# Panics` on the item states the contract and the
decision (HY-04, kept-as-is). The adjacent `WsClient::send_binary`/
`send_binary_piece`/`send_text` unwraps got the same treatment (test
client that can't send = broken test, not a runtime branch). The
`test-support` module remains the documented exception to
no-panics-in-library-code.

**Sequencing note**: the sweep landed after the client task as
planned; doing it last meant documenting the *final* shapes
(`PublishSchemaCache` in the gateway, `RetryConfig` on the client)
once — no churn.

## Summary

- ~101 → **0** missing-docs warnings; `#![deny(missing_docs)]` in
  `src/lib.rs` is the enforcement (stronger than CI rustdocflags:
  every build, no CI wiring to maintain). `RUSTDOCFLAGS="-D warnings"
  cargo doc --no-deps` is also fully clean (private-link and
  redundant-link warnings fixed opportunistically — HY-10 fully
  resolved).
- HY-11: `docs/` + `tasks/` excluded; publish dry-run = 38 files,
  ~889 KiB; decision + rationale + degradation story above.
- HY-04: kept + documented (`# Panics` with the unreachable-failure
  rationale and the test-support exception note).
- Verified: `cargo test` (299 + 5 TLS), `--all-features` (370 + all
  suites), `--no-default-features` (299; same 4 pre-existing
  no-default-feature warnings as the base commit), `clippy --all-
  targets -- -D warnings` (default + all-features), `fmt --check`,
  `cargo doc --no-deps` clean under `-D warnings`,
  `cargo publish --dry-run --allow-dirty` clean.