Documentation: cover every module, map what lives where, and halve CI wall time

[Magic-Man-us]

Five commits, 96 files. No library behaviour changes — every src/ edit is a doc comment.

All six checks green on 9194eeb, and the CI claim in the title is now measured rather than predicted:

	before	after
test job	14m52s	6m46s
Coverage	(inside test)	8m18s, in parallel
whole PR, wall clock	~15–19 min	11m07s, now bounded by Miri

test is no longer even on the critical path.

---

CI ran the test suite twice

The test job ran cargo test and then cargo llvm-cov as consecutive steps, so its wall time was their sum.

llvm-cov is not a reporting step that reads what cargo test produced — there is nothing to read. It compiles the crate with -C instrument-coverage into its own target directory and runs the whole suite again, because running the tests is how it collects coverage. The two do the same work twice whatever we do; the only question is series or parallel. They are now separate jobs.

Two other things turned up in that file:

• The cache was doing nothing. It cached ~/.cargo/registry and ~/.cargo/git, which are empty for a crate whose Cargo.lock holds exactly one package — itself — and keyed on hashFiles('**/Cargo.lock'), which therefore never changes. After the first save it restored a stale tree and never wrote again; every run logged Cache hit occurred on the primary key, not saving cache. Replaced with Swatinem/rust-cache@v2, which verify.yml already used. The two jobs get separate keys deliberately — instrumented artifacts fingerprint differently, so sharing one cache would thrash it. This is most of why test more than halved.
• The separate cargo build step is gone; cargo test builds the same artifacts.

cargo doc emitted 81 warnings

Rendering bugs rather than style. Rustdoc parses [k] in a formula as an intra-doc link, so X[k] = Σ x[n]·e^(−j2πkn/N) published with two broken links in it. It parses <counts> and <R> as HTML tags, so those doc comments lost content entirely in the rendered output.

Fifty-one doc comments across transforms, statistics, signal_processing, dsp, linalg, biophysics, chemistry, color_science, manifold, fractals, sim, numerical and core. 81 → 0, and CI now builds docs with RUSTDOCFLAGS=-D warnings.

Three needed more than backticks: the two-line Mur boundary formulas in wave_sim.rs became a ```text block, which is what they always were; MAX_QUBITS, RESTARTS and mc_table are private so rustdoc cannot link to them; and audio/effects.rs linked [`read`] from a sibling method without the Self:: prefix.

63 modules had no documentation at all

Including src/lib.rs — the landing page of the entire generated documentation was empty.

lib.rs now carries an orientation page: what the library is for, a table routing all 71 top-level modules by subject, and the three conventions a caller needs (SI units and radians; f64 except where exactness is the point; and that monte_carlo::Rng is an LCG whose low bits are short-period, so Rng::below is the one to use).

The other 62 are written from what they contain, and each says something a reader would otherwise have to derive — that Sabine's reverberation formula never reaches zero however absorptive the room and Eyring's does; that metals yield on deviatoric stress alone, which is why von Mises ignores hydrostatic pressure; that L4 and L5 are stable below a mass ratio of about 1/24.96, which is why Jupiter's Trojans stay put; that the buildup factor matters because ignoring it underestimates dose behind a thick shield.

docs/GUIDE.md — documentation a person can read

The README is a catalogue, MODULE_MAP is a table, rustdoc is an index. None of them teaches anyone to use this.

The guide walks through the library by doing things with it: putting a spacecraft in orbit and transferring it to geostationary, pulling a 440 Hz tone out of noise louder than the signal, solving −u″ = f and proving the answer converges at the rate the theory predicts, and the tools for not being wrong.

No code block in it is written by hand. Each chapter is an example file, and the output quoted is what that file actually prints:

chapter	file	what it demonstrates
2	examples/guide_02_orbit.rs	elements from state vectors, Hohmann transfer, vis-viva closure
3	examples/guide_03_signal.rs	FFT, FIR design, Welch PSD
4	examples/guide_04_fem.rs	finite elements and measured convergence rates
5	examples/guide_05_correctness.rs	units, formula checking, exact rationals

All four assert their own results and are run by CI, so a chapter describing something that does not work fails the build. The numbers earn their place by being real: the ISS's actual 7,673 m/s and 92.4 minutes, 3,857 m/s and 5.3 hours for the transfer, 67 dB of filter rejection, and L2/H1 rates of 2.00/1.00 for P1 and 3.00 for P2 against theory stated before the measurement.

It also says what a reference cannot — why finite elements rather than finite differences, why an error that merely shrinks proves nothing while one shrinking at exactly h² settles it — and closes with what will bite you: the LCG's low bits, conditional stability of explicit stepping, and that pcg_jacobi's tolerance is relative to the right-hand side.

docs/MODULE_MAP.md — what exists where

A size-annotated tree of all 295 modules, tables by subject area, and a row per module with line count, public item counts and summary. Generated by tools/gen_module_map.py, because a hand-maintained map of 295 modules is stale the day after.

Getting the totals to reconcile took two corrections: verification is declared mod, not pub mod, so counting it gave 72 top-level modules against the README's 71; and excluding lib.rs from the line total made the map disagree with wc -l over src/ by exactly lib.rs's length. The map's 266,122 now matches wc -l exactly.

Copilot's review found two real bugs — both fixed in b90cd00

Verified against the source before changing anything:

• Free functions were told from methods by column-zero indentation. Wrong for an indented pub fn inside an inline pub mod { ... } — there are 175 of those (89 in clifford.rs across its cl3/pga3/cga3/sta modules, 85 in the fractals/ presets, one macro template). Now classified by the enclosing impl block, tracked on a stack so a multi-line where clause still opens the body at the right line. Counts move to 4,124 free / 2,241 methods; the sum is unchanged at 6,365, which is the signature of a pure misclassification.
• Public types were matched on the raw line, so only column-zero ones counted — missing CgaObject and the kdtree macro type. 429 → 431.
• The tree flattened nested directories. src/numerical/ode/ came out as an ode.rs sibling with its four files hoisted up beside bvp.rs, ordering broken with them. Now recursive.

The map states the one limitation neither bug caused: the count is syntactic, so a macro-generated item is counted once where the macro defines it rather than once per expansion.

README

Claimed 1,659 tests at 99.98% coverage across 67 files, and described none of the Part 3 or Part 4 work. Rewritten against measured numbers, with the governing equations per domain — Galerkin orthogonality and the Pythagoras identity for FEM, the leapfrog energy and Courant condition for FDTD, Buckingham's theorem as a rank computation, LP duality and KKT, Black–Scholes with put–call parity, Hodgkin–Huxley, Marchenko–Pastur.

Two verification passes on the document itself: a script checked all 158 module references in the prose against the source tree (every one resolves, all 71 top-level modules covered), and proofreading the equations caught a mismatched contraction index in the Riemann tensor and an ambiguous Marchenko–Pastur support.

New CI gates

Six, all tested in both directions before committing, all passing on their first real run:

Gate	Catches
cargo run --example readme_quickstart	the README's front-page example rotting
the four guide_* examples	a guide chapter describing code that does not work
cargo doc under -D warnings	doc rendering bugs
gen_module_map.py --check	the generated map going stale
check_module_docs.py	a module with no //! summary

The last matters because nothing else catches it: rustdoc's missing_docs covers items, not modules, so an undocumented module is completely silent.

Verification

• 4,193 lib tests, 577 property tests, 2 doc tests, five examples — all passing
• cargo doc --no-deps clean under -D warnings (from 81)
• 296 of 296 source files carry a module doc
• cargo clippy --all-targets -- -D warnings clean
• cargo +nightly-2025-11-21 check --lib --tests clean (the Kani-pinned toolchain)
• All six CI checks green; mergeable_state: clean

One open question

Coverage still runs on PRs, just in parallel rather than in series. If you would rather it ran only on main pushes it disappears from PR latency entirely — one line to change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VUkMGnfUbaopkUJLWeYCYi

[Copilot]

🟡 Changes recommended

tools/gen_module_map.py has verified counting and tree-rendering bugs that make the generated docs/MODULE_MAP.md inaccurate.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR is a documentation and CI-quality pass for the crate: it adds/repairs rustdoc module-level docs across the codebase, introduces a generated module map, and reduces CI wall time by splitting coverage into a separate job and adding doc/module-map gates.

Changes:

• Added module-level (//!) documentation across many src/ modules and corrected rustdoc-rendering pitfalls in formula-like doc comments.
• Added generated documentation artifacts and tooling (docs/MODULE_MAP.md, tools/gen_module_map.py, tools/check_module_docs.py) and CI checks to keep them current.
• Updated CI workflow to run tests, docs, module-map, and module-doc checks in the test job and run cargo llvm-cov in a parallel coverage job (with rust-cache).

File summaries

File	Description
tools/gen_module_map.py	New generator for docs/MODULE_MAP.md (counts + summaries + tree + tables).
tools/check_module_docs.py	New gate to ensure every Rust source file starts with a //! module summary.
src/waves.rs	Added module-level documentation.
src/trigonometry.rs	Added module-level documentation.
src/transforms/fft.rs	Fixed rustdoc rendering by backticking formula-like text in doc comments.
src/thermodynamics.rs	Added module-level documentation.
src/statistics/fourier.rs	Backticked formula-like doc text to avoid rustdoc link parsing issues.
src/spatial/octree.rs	Added module-level documentation.
src/solid_mechanics.rs	Added module-level documentation + cross-references.
src/sim/wave_sim.rs	Added module-level docs + formatted Mur boundary formulas as text block.
src/sim/rigid_body.rs	Added module-level documentation.
src/sim/mod.rs	Added module-level documentation and cross-references to other solver modules.
src/sim/heat_sim.rs	Added module-level docs + adjusted some unit wording in field docs.
src/sim/fluid_sim.rs	Added module-level documentation.
src/sim/em_sim.rs	Added module-level documentation.
src/sim/cloth_sim.rs	Added module-level documentation.
src/signal_processing/mod.rs	Added module-level documentation + rustdoc link fix (mod@...).
src/rf.rs	Added module-level documentation.
src/relativity.rs	Added module-level documentation.
src/radiation.rs	Added module-level documentation + cross-references.
src/quaternion.rs	Added module-level documentation + cross-reference.
src/quantum/circuit.rs	Replaced non-linkable private constant link with literal + value.
src/propulsion.rs	Added module-level documentation + cross-reference.
src/plasma.rs	Added module-level documentation + cross-reference.
src/photonics.rs	Added module-level documentation.
src/particle_physics.rs	Added module-level documentation.
src/optimization/mod.rs	Added module-level documentation with submodule pointers.
src/optics.rs	Added module-level documentation + cross-reference.
src/numerical/ode/explicit.rs	Backticked function signature text in docs to avoid rustdoc parsing.
src/numerical/interpolate.rs	Backticked indexing/math-like doc text.
src/nuclear.rs	Added module-level documentation + cross-reference.
src/nonlinear.rs	Added module-level documentation + cross-reference.
src/neutronics.rs	Added module-level documentation.
src/monte_carlo/mod.rs	Added module-level documentation with RNG warning section.
src/mesh/isosurface.rs	Replaced non-linkable private function link with literal identifier.
src/math.rs	Added module-level documentation + cross-reference to CODATA constants.
src/materials/mod.rs	Added module-level documentation describing tables.
src/materials/gases.rs	Added module-level documentation.
src/materials/fluids.rs	Added module-level documentation.
src/materials/elements.rs	Added module-level documentation.
src/materials/common.rs	Added module-level documentation.
src/manifold/polytope4.rs	Backticked [0,1]^n to avoid rustdoc link parsing.
src/manifold/metric.rs	Backticked math-like identifiers in docs to avoid intra-doc links.
src/manifold/clifford.rs	Backticked <...>-like content to avoid HTML-tag parsing.
src/magnetohydrodynamics.rs	Added module-level documentation.
src/linalg/tridiagonal.rs	Backticked equation to avoid rustdoc link parsing.
src/linalg/mod.rs	Added module-level documentation + backticked transpose equation.
src/linalg/matrix.rs	Backticked transpose equation.
src/lib.rs	Added crate-level landing/orientation docs + conventions + example snippet.
src/learn/cluster.rs	Replaced non-linkable private constant link with literal + value.
src/information_theory.rs	Added module-level documentation.
src/gravitation.rs	Added module-level documentation + cross-reference.
src/geophysics.rs	Added module-level documentation.
src/geometry/mod.rs	Added module-level documentation + cross-references.
src/general_relativity.rs	Added module-level documentation + cross-references.
src/fractals/mod.rs	Added module-level documentation + cross-reference.
src/fractals/lsystem.rs	Backticked L-system rewrite strings to avoid rustdoc parsing issues.
src/fractals/automata.rs	Backticked bracket/index and quoted-string examples to avoid rustdoc parsing.
src/fractals/attractors.rs	Backticked indexing expression in docs.
src/fluids.rs	Added module-level documentation + cross-reference.
src/fluid_instabilities.rs	Added module-level documentation.
src/electronics.rs	Added module-level documentation.
src/electromagnetism.rs	Added module-level documentation.
src/dsp/windows.rs	Backticked formula-like docs for window definitions.
src/curves.rs	Added module-level documentation + cross-references.
src/core/dual.rs	Backticked Jacobian indexing expression in docs.
src/control_systems/mod.rs	Added module-level documentation.
src/continuum_mechanics.rs	Added module-level documentation.
src/color_science.rs	Added module-level documentation + backticked range notation in docs.
src/classical.rs	Added module-level documentation.
src/chemistry.rs	Added module-level documentation + backticked equations in docs.
src/biophysics/mod.rs	Backticked equations/tuples in docs to avoid rustdoc parsing issues.
src/audio/effects.rs	Fixed intra-doc link to sibling method with Self:: prefix.
src/atmosphere.rs	Added module-level documentation.
src/astrophysics/tidal.rs	Added module-level documentation.
src/astrophysics/orbital_elements.rs	Added module-level documentation + cross-reference.
src/astrophysics/nbody.rs	Added module-level documentation + corrected cross-reference target.
src/astrophysics/mod.rs	Added module-level documentation describing submodules.
src/astrophysics/magnetosphere.rs	Added module-level documentation.
src/astrophysics/lagrange.rs	Added module-level documentation.
src/astrophysics/habitable_zone.rs	Added module-level documentation.
src/astrophysics/gravitational_waves.rs	Added module-level documentation.
src/astrophysics/collisions.rs	Added module-level documentation.
src/acoustics.rs	Added module-level documentation.
README.md	Major rewrite: updated metrics, expanded module descriptions, added CI/testing/docs/module-map explanations, and updated badges.
examples/readme_quickstart.rs	New CI-run example mirroring README quick start snippet.
docs/ROADMAP_PART4.md	Marked roadmap status as complete and added context on delivered work.
docs/MODULE_MAP.md	New generated module map output committed to the repo.
.github/workflows/verify.yml	Updated comment count about Miri-skipped tests.
.github/workflows/ci.yml	Split coverage into separate job, added rust-cache, added docs/module-map/module-doc gates, and ran README quickstart example in CI.

Review details

Suppressed comments (1)

tools/gen_module_map.py:97

• Public-item counting in scan() currently relies on whether the line starts at column 0 to decide between “free function” vs “method”, and only counts pub struct/enum/trait when they start at column 0. This produces incorrect totals for nested modules (e.g. indented pub fn in pub mod presets { ... }) and misses public types declared inside nested modules (e.g. pub enum inside pub mod ... {}).

• Files reviewed: 90/90 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Magic-Man-us]

Confirmed and fixed in b90cd00.

I checked before changing anything: there are 175 indented pub fn outside any impl — 89 in manifold/clifford.rs across its cl3, pga3, cga3 and sta modules, 85 across the four fractals/ preset modules, and one macro template in units/quantity.rs. Every one was landing in the method column.

scan() now tracks enclosing impl blocks on a stack, so a multi-line impl header with a where clause still opens the body at the line that actually opens the brace, and a pub fn is a method iff that stack is non-empty.

Your suppressed comment on the same function was also right, so I fixed that too: PUB_TYPE was matched against the raw line rather than the stripped one, so only types at column zero counted. That missed CgaObject inside clifford's pub mod sta and the k-d tree type inside spatial/kdtree.rs's macro.

Totals move from 3,949/2,416 to 4,124 free functions and 2,241 methods. The sum is unchanged at 6,365, which is the expected signature of a pure misclassification — both bugs only moved items between the two columns. Types go 429 → 431. README updated to match.

One case neither bug caused, now stated in the generated map so a reader is not misled: the count is syntactic, so a macro-generated item is counted once where the macro defines it rather than once per expansion. That under-counts units::quantity by roughly thirty constructors and spatial::kdtree by one type.

---

Generated by Claude Code

[Magic-Man-us]

Confirmed and fixed in b90cd00. src/numerical/ode/ was exactly the case that broke, and it was worse than losing the directory — the ordering went with it:

├── numerical/                     2,563
│   ├── bvp.rs                       201
│   ├── integrate.rs                 270
│   ├── interpolate.rs               648
│   ├── ode.rs                        11     ← ode/mod.rs, rendered as a file
│   ├── adaptive.rs                  309     ← hoisted a level, and out of order
│   ├── explicit.rs                   63
│   ├── implicit.rs                  232
│   ├── symplectic.rs                125
│   └── roots.rs                     280

The renderer made one flat pass and printed each module's last path segment, so nothing below the first directory level could survive. It is now recursive over the module hierarchy:

├── numerical/                     2,563
│   ├── bvp.rs                       201
│   ├── integrate.rs                 270
│   ├── interpolate.rs               648
│   ├── ode/                         740
│   │   ├── adaptive.rs              309
│   │   ├── explicit.rs               63
│   │   ├── implicit.rs              232
│   │   └── symplectic.rs            125
│   └── roots.rs                     280

A directory's figure is now its own mod.rs plus everything beneath it, which the map states: ode/ is 740 = its four files at 729 plus its 11-line mod.rs. roots.rs sorts after ode/ again.

numerical/ode is currently the only directory more than one level deep, so this was the only visible instance — but the flat pass would have broken silently on the next one, which is why it was worth fixing rather than special-casing.

---

Generated by Claude Code