docs: ENG-4684 doctests + deny(missing_docs) + clippy::pedantic

[jimbofreedman]

Closes ENG-4684 — https://app.clickup.com/t/86c9umm6g

Promotes the crate to library-grade docs and lints: every public item documented, every doc example a live doctest, clippy pedantic enforced across every target.

What changed

Area	Change
src/lib.rs	The ticket's six-lint #![deny(...)] group + #![warn(clippy::pedantic, clippy::nursery)] + a three-entry allow list, each entry justified inline
src/loader.rs	# Examples on all 9 public methods, # Errors on every Result-returning fn, # Panics on archived; use_self ×5, #[must_use] ×5, const fn resolution_km
src/graph.rs, src/data.rs	All 9 missing_docs items documented with units, ranges and index semantics
build/*.rs, src/bin/, benches/, 18 × tests/*.rs	Pedantic clean — mostly doc backticks, plus justified allow blocks
.github/workflows/ci.yaml	One line: -W clippy::pedantic on the existing clippy step
Cargo.toml	[lints.clippy] pedantic baseline — see Two decisions for the reviewer

Doctests: 1 ignored / 0 passed → 15 passed / 0 ignored. Each loads a real 50 km graph and asserts real values (7,390 nodes, 15,498 edges, a 16,354 km Suez route) — no fixture, no network, 0.4 s total. Graph::load, Graph::from_bytes and Graph::route are each covered twice.

Acceptance criteria

AC	Command	Result
AC1	RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --document-private-items --all-features	clean
AC2	RUSTDOCFLAGS="-D rustdoc::broken_intra_doc_links" cargo doc --no-deps --all-features	clean
AC3	cargo clippy --all-targets --all-features -- -D warnings -W clippy::pedantic	exit 0
AC4	cargo test --doc --all-features	15 passed, 0 ignored
—	cargo test --all-features	190 passed, 0 failed (29 targets)
—	cargo +1.93.0 test --doc --all-features (MSRV)	15 passed
—	cargo fmt --all --check	clean

The new gates were verified to actually bite, not just be declared: an undocumented pub field fails cargo check, and a fresh pedantic violation is a hard error under -D warnings.

Reviewability — ~6 files need close reading, the rest are mechanical

• Semantic: src/lib.rs, src/graph.rs, src/data.rs, src/loader.rs, tests/lint_state.rs, tests/ci_workflow.rs, Cargo.toml
• Mechanical: build.rs + build/*.rs, src/bin/rustyroute.rs, benches/route.rs, 18 tests/*.rs. ~110 findings are one-token doc backticks; 72 more are a single crate-root allow in tests/vendored_data.rs (the FIPS 180-4 SHA-256 constant table, which must stay character-for-character comparable to the spec).

Two decisions for the reviewer

1. Cargo.toml [lints.clippy] pedantic is an addition beyond the ticket and can be reverted on its own without unpicking anything else.

The ticket puts the lints in src/lib.rs, but crate-root attributes reach only the library — build.rs, tests/*, benches/ and src/bin/ are separate crate roots. Without this table those ~120 pedantic findings are gated solely by one line of CI YAML, invisible to .pre-commit-config.yaml's clippy hook and to every contributor's editor. Proven empirically: with the table, a bare cargo clippy flags a pedantic violation in build.rs; without it, zero diagnostics. priority = -1 keeps per-file allows winning.

2. The missing_errors_doc / missing_panics_doc allows are now dead weight. They're kept because the ticket specifies them, but this PR adds # Errors to every Result-returning public fn and a real # Panics to archived — leaving one missing_panics_doc site and two missing_errors_doc sites, all fixed at source. Dropping both allows would convert two apologetic allows into two live gates. Happy to do it in this PR if you agree.

Things worth knowing

• The ticket's suggested justification for missing_panics_doc — "no public panics" — is factually wrong. Graph::archived and Graph::route both .expect(...) (src/loader.rs:290, :495). Replaced with an accurate comment.
• src/graph.rs exposes no public functions (only two already-documented pub consts and struct fields), so the ticket's "# Examples per public function" clause is vacuous there — that file is docs-only, not under-delivered.
• clippy::suboptimal_flops was deliberately NOT fixed in haversine_km or build/geometry.rs. mul_add's single fused rounding step would shift results in the last bits, rebaking every .rkyv archive and drifting the golden distance table. Allowed with that reasoning inline; tests/golden_routes.rs is the tripwire and stays green.
• bytes_for was deliberately NOT made const fn. tests/data_module.rs asserts on its exact signature string as an ENG-4688 wasm-gate guard; a nursery cosmetic isn't worth breaking a live guard. Site-allowed instead.
• tests/lint_state.rs and tests/ci_workflow.rs only ever assert more. lint_state goes from 1 assertion to 5 (keeping the forbid(unsafe_code) rejection); ci_workflow gains a pedantic-flag assertion and a check that the doctest carrier is never narrowed — nothing in CI names cargo test --doc, so the 15 doctests ride on cargo test --all-features.
• Sequencing from the ticket is satisfied: ENG-4679 is already merged, and the mmap #[allow(unsafe_code)] + SAFETY comment were already in place.

Residual risk: CI runs stable, newer than the local 1.97.1 used here. Pedantic/nursery lint sets shift between releases, so a follow-up lint-name fix after the first CI run is possible.

🤖 Generated with Claude Code

[codspeed-hq]

Merging this PR will not alter performance

✅ 6 untouched benchmarks

---

_{Comparing worktree-ENG-4684 (635155f) with main (c248547)}

[Copilot]

Pull request overview

Raises documentation and lint strictness across the crate to “library-grade” standards by enforcing missing_docs, enabling clippy pedantic/nursery, and converting doc examples into runnable doctests across library + supporting targets (tests/build/bin/benches).

Changes:

• Added crate-level lint posture (deny group + clippy warn groups + narrowly-justified allows) and package-wide clippy pedantic baseline via Cargo.toml.
• Expanded public API docs across src/loader.rs, src/graph.rs, src/data.rs (examples/errors/panics, doctests, #[must_use], and some signature/formatting cleanups).
• Updated CI to gate pedantic via a clippy flag, and performed mechanical doc/lint cleanups across build code, tests, benches, and bin.

Reviewed changes

Copilot reviewed 36 out of 36 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/vendored_data.rs	Adds crate-root clippy allow block with rationale for FIPS-transcribed SHA-256 constants.
tests/tampered_gpkg_panic.rs	Mechanical doc backticks/wording updates in test docs.
tests/route_smoke.rs	Adds justified crate-root clippy::float_cmp allow for exact-zero assertions.
tests/release_plz_config.rs	Doc backticks + minor AC mapping text tweaks.
tests/release_dist_workflow.rs	Doc backticks + minor AC mapping text tweaks.
tests/pre_commit_e2e.rs	Refactors Result handling with is_ok_and for pedantic cleanliness.
tests/pre_commit_config.rs	Refactors Option handling with map_or for pedantic cleanliness.
tests/lint_state.rs	Expands lint-posture “contract tests” to assert deny/warn/allow state and Cargo.toml clippy lints.
tests/graph_load.rs	Doc wording/backticks + poison-lock handling refactor (PoisonError::into_inner).
tests/golden_routes.rs	Adds justified crate-root clippy::float_cmp allow for exactness checks.
tests/feature_matrix.rs	Adds justified allow for manual_assert + minor refactors for pedantic.
tests/env_data_dir.rs	Refactors poison-lock handling (PoisonError::into_inner).
tests/downstream_consumer_smoke.rs	Refactors env var handling with map_or_else for pedantic.
tests/data_module.rs	Mechanical doc backticks for exported const name.
tests/codspeed_workflow.rs	Mechanical doc backticks/wording consistency.
tests/cli_smoke.rs	Mechanical doc backticks/wording consistency.
tests/ci_workflow.rs	Adds assertions that CI clippy includes pedantic flag and that doctests aren’t narrowed away.
tests/build_helpers.rs	Adds justified crate-root clippy::unreadable_literal allow for transcribed floats.
tests/build_artifacts.rs	Doc backticks + targeted cast_possible_truncation allow with rationale.
tests/audit_workflow.rs	Mechanical doc backticks.
src/loader.rs	Major public API doc expansion (Errors/Panics/Examples), doctests, #[must_use], and minor signature/formatting cleanups.
src/lib.rs	Adds crate-level Examples section + consolidated lint posture (deny group, clippy warn groups, justified allows).
src/graph.rs	Documents schema items (units/ranges/index semantics) to satisfy missing_docs.
src/data.rs	Documents feature-gated byte slices via macro-generated docstrings; adds justification for a lint allow.
src/bin/rustyroute.rs	Mechanical doc backticks/wording consistency.
Cargo.toml	Adds [lints.clippy] pedantic baseline with low priority and rationale.
build/mod.rs	Minor formatting refactors + generated-code lint allow to prevent unfixable spans in include! output.
build/groups.rs	Mechanical doc backticks + module-level lint allows with rationale.
build/gpkg.rs	Mechanical doc backticks/wording updates.
build/gpkg_io.rs	Adds module-level missing_errors_doc allow with rationale for test inclusion context.
build/geometry.rs	Mechanical doc backticks + module-level lint allows + a justified match_same_arms allow.
build/csr.rs	Mechanical doc backticks + module-level lint posture allows with rationale.
build/archive.rs	Mechanical doc backticks/wording consistency.
build.rs	Mechanical doc backticks/wording consistency.
benches/route.rs	Mechanical doc backticks/wording consistency.
.github/workflows/ci.yaml	Adds -W clippy::pedantic to the clippy step.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 36 out of 36 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (2)

src/loader.rs:145

• This doctest is now runnable and asserts on the loaded graph, but it calls Graph::load(50), which can fail on developer machines when $RUSTYROUTE_DATA_DIR is set (even if CI passes). Since the example’s goal is demonstrating the OnceLock + Box::leak pattern, using Graph::from_bytes(data::BYTES_50KM) keeps it hermetic and still runnable.

/// assert_eq!(graph().resolution_km(), 50);
/// assert!(std::ptr::eq(graph(), graph()));

src/loader.rs:398

• This example runs Graph::load(50)?, so it can fail in environments where $RUSTYROUTE_DATA_DIR is set (even though CI is clean). Making the snippet no_run keeps it as a compile-checked doctest without depending on the caller’s runtime environment.

    /// ```
    /// # use rustyroute::{Graph, data};
    /// assert_eq!(Graph::load(50)?.resolution_km(), 50);
    /// assert_eq!(Graph::from_bytes(data::BYTES_50KM)?.resolution_km(), 0);