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

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
review-001-missing-docs-sweep	missing_docs sweep + publish-prep decisions (HY-02, HY-04, HY-11)	completed	review-001-client-config-and-cert-coverage	moderate	low	project	implementation	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

• cargo doc with -W missing_docs (as deny) exits clean — 0 warnings
• Enforcement landed (CI rustdocflags or lint config) so it stays clean
• HY-11 decision recorded; cargo publish --dry-run --allow-dirty package contents match the decision
• HY-04 resolved (documented or restructured)
• 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.