docs: resolve cargo evaluate documentation findings

[martintmk]

Summary

• resolve all 159 documentation findings from the original full-workspace cargo-evaluate report
• add crate landing-page examples, module summaries, canonical Errors/Panics/Safety/Examples sections, and correct rustdoc re-export rendering
• regenerate all affected crate READMEs from their rustdoc source
• add narrowly scoped evaluate exceptions only where repeated semantic findings exceeded the guideline or could not inspect the defining API

Cargo evaluate

The final cargo evaluate -Z mode=diff -Z base=main report contains zero documentation-category findings. The command still exits non-zero because this PR intentionally does not address unrelated non-documentation rules.

Validation

Formatting, Clippy, default-feature doctests, all-feature doctests, workspace build, rustdoc, Cargo sorting, README generation/check, spelling, license headers, and SemVer analysis passed. Compile-based workspace checks excluded only the unchanged msvc_spectre_libs package because this machine does not have the Visual Studio Spectre-mitigated libraries installed.

cargo deny is currently blocked by RUSTSEC-2026-0285 in rustls 0.23.44, which is already present on main. Updating a TLS dependency is intentionally outside this documentation-only PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.0%. Comparing base (84083b8) to head (ae6e53d).
⚠️ Report is 5 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #762   +/-   ##
=======================================
  Coverage   100.0%   100.0%           
=======================================
  Files         634      634           
  Lines       84746    84746           
=======================================
  Hits        84746    84746           

Flag	Coverage Δ
linux	99.9% <ø> (-0.1%)	⬇️
linux-arm	99.9% <ø> (-0.1%)	⬇️
scheduled	?
windows	99.9% <ø> (-0.1%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[martintmk]

Posted by an AI agent

Review Lens completed all ten required areas at this head. I found three non-blocking documentation contract issues; the inline comments contain the details. cargo check --locked passed for the workspace containing all changed crates. No approval or change-request vote was submitted because this is my own PR.

[martintmk]

Posted by an AI agent · Non-blocking

The rallocator macro documents compile-time validation as a runtime panic

Problem
The new # Panics section says malformed size classes or a zero partial_slab_scan_limit panic during allocator construction, but Rallocator::VALIDATE_TUNABLES is an associated const containing assert!, and Rallocator::new reads that const while initializing the macro-generated static. Invalid tunables therefore fail constant evaluation and reject the consumer build rather than producing a runtime panic.

Why this matters
Consumers get the wrong failure model for configuration errors and may look for a runtime panic path that cannot occur.

Suggested fix
Replace the # Panics contract with text stating that invalid tunables cause a compile-time error, and keep the accepted layout constraints alongside the macro options.

[martintmk]

Posted by an AI agent · Non-blocking

execute_or_abandon documents mutually exclusive timeout outcomes

Problem
The new contract says a timeout returns None at crates/testing_aids/src/lib.rs:65, while the unchanged # Panics section at line 70 says the same timeout panics. The implementation at line 98 converts both RecvTimeoutError::Timeout and the disconnected channel produced by a background panic to None; only the mutation-testing branch executes f inline and propagates its panic.

Why this matters
Callers cannot tell whether they should handle None or catch a panic, and the current text also incorrectly promises propagation of ordinary background-thread panics.

Suggested fix
Document that normal-mode timeouts and background panics return None, and scope the panic guarantee to MUTATION_TESTING=1 (or change the implementation if panic propagation is intended).

[martintmk]

Posted by an AI agent · Non-blocking

OnceLock overstates at-most-once initializer execution

Problem
The new module summary says that when callers race, “only one initialization runs,” but get_or_init explicitly documents at lines 64-65 that a panicking initializer leaves the cell empty and a later call runs another initializer. The wrapper delegates to std::sync::OnceLock, so initializer side effects can occur more than once across failed attempts.

Why this matters
Readers may treat initializer side effects as globally at-most-once even though panic recovery permits another execution.

Suggested fix
Qualify the summary to say that only one initializer runs at a time and that all callers observe the same successfully initialized value; retain the existing panic/retry contract.