From 737611ca576676743f03b702c628d5db2348306b Mon Sep 17 00:00:00 2001 From: axect Date: Fri, 10 Jul 2026 13:51:07 +0800 Subject: [PATCH 1/2] DOCS: Replace source layout table with pointer to docs.rs module index (JOSS jonaspleyer #99) The hand-maintained module table duplicated the module index that rustdoc generates on docs.rs and could only drift out of sync. What remains is the repo-only fact rustdoc cannot show: src/grave/ is retired code excluded from compilation. --- CONTRIBUTING.md | 17 ++--------------- 1 file changed, 2 insertions(+), 15 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index eee2e8f..f62e2ea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,21 +41,8 @@ Peroxide follows the [Gitflow workflow]. A few practical rules: ## Source layout -A high-level map of `src/`; see each module's `mod.rs` and the [API docs](https://docs.rs/peroxide) for details. - -| Module | Purpose | -| ------------------ | ------------------------------------------------------------------ | -| [`structure`](src/structure) | Core data structures: `Matrix`, `Vec` extensions, `DataFrame`, `Polynomial`, `Jet` forward AD | -| [`numerical`](src/numerical) | Numerical algorithms: ODE solvers, integration, interpolation, splines, root finding, optimization, eigenvalues | -| [`statistics`](src/statistics) | Probability distributions, RNG wrappers, ordered statistics | -| [`complex`](src/complex) | Complex vectors, matrices, and integrals (`complex` feature) | -| [`special`](src/special) | Special functions (wrapper of `puruspe`) | -| [`traits`](src/traits) | Shared trait definitions (math, functional programming, pointers) | -| [`macros`](src/macros) | R / MATLAB / Julia style macros | -| [`fuga`](src/fuga), [`prelude`](src/prelude) | The two user-facing import styles (explicit vs simple) | -| [`util`](src/util) | Constructors, printing, plotting, low-level helpers | -| [`ml`](src/ml) | Basic machine learning tools (beta) | -| [`grave`](src/grave) | Retired implementations kept for reference; not compiled | +The directories under `src/` map one-to-one to the public modules, so the module index in the [API docs](https://docs.rs/peroxide) doubles as the source map; start from a module's documentation and its `mod.rs`. +The only exception is `src/grave/`, which holds retired implementations kept for reference and is excluded from compilation. ## Code of conduct From ee6030d35b927757b53017ec019a055f2bae39f7 Mon Sep 17 00:00:00 2001 From: axect Date: Fri, 10 Jul 2026 13:57:37 +0800 Subject: [PATCH 2/2] DOCS: Move module descriptions from CONTRIBUTING table into module docs The removed source layout table carried descriptions that existed nowhere in rustdoc: complex and traits had no module docs at all, and several first lines (Useful macros, Statistical Modules, Main structures) were too vague to serve as an index. Each module now carries its one-line purpose in its own mod.rs, so the docs.rs module index is the single source for the source map and stays in sync with the code by construction. --- src/complex/mod.rs | 2 ++ src/macros/mod.rs | 2 +- src/ml/mod.rs | 2 +- src/numerical/mod.rs | 2 +- src/statistics/mod.rs | 2 +- src/structure/mod.rs | 6 +++--- src/traits/mod.rs | 2 ++ src/util/mod.rs | 2 +- 8 files changed, 12 insertions(+), 8 deletions(-) diff --git a/src/complex/mod.rs b/src/complex/mod.rs index b17fc18..16a7e62 100644 --- a/src/complex/mod.rs +++ b/src/complex/mod.rs @@ -1,3 +1,5 @@ +//! Complex vectors, matrices, and integrals, enabled by the `complex` feature + use num_complex::Complex; pub type C64 = Complex; diff --git a/src/macros/mod.rs b/src/macros/mod.rs index 7b97f1f..20ca775 100644 --- a/src/macros/mod.rs +++ b/src/macros/mod.rs @@ -1,4 +1,4 @@ -//! Useful macros +//! R / MATLAB / Julia style macros pub mod julia_macro; pub mod matlab_macro; diff --git a/src/ml/mod.rs b/src/ml/mod.rs index e08e851..d63c3a2 100644 --- a/src/ml/mod.rs +++ b/src/ml/mod.rs @@ -1,3 +1,3 @@ -//! Machine learning tools +//! Basic machine learning tools (beta) pub mod reg; diff --git a/src/numerical/mod.rs b/src/numerical/mod.rs index 0a21bfc..e8bfe54 100644 --- a/src/numerical/mod.rs +++ b/src/numerical/mod.rs @@ -1,4 +1,4 @@ -//! Differential equations & Numerical Analysis tools +//! Numerical algorithms: ODE solvers, quadrature, interpolation, splines, root finding, optimization, and eigenvalue computation pub mod eigen; pub mod integral; diff --git a/src/statistics/mod.rs b/src/statistics/mod.rs index c128b65..8f2b93b 100644 --- a/src/statistics/mod.rs +++ b/src/statistics/mod.rs @@ -1,4 +1,4 @@ -//! Statistical Modules +//! Probability distributions, random sampling, and statistical operations //! //! * Basic statistical tools - `stat.rs` //! * Popular distributions - `dist.rs` (`rand` feature) diff --git a/src/structure/mod.rs b/src/structure/mod.rs index 666bbee..5951c36 100644 --- a/src/structure/mod.rs +++ b/src/structure/mod.rs @@ -1,8 +1,8 @@ -//! Main structures for peroxide +//! Core data structures: `Matrix`, `Vec` extensions, `DataFrame`, `Polynomial`, and const-generic forward-mode AD (`Jet`) //! -//! * Matrix +//! * Matrix (dense & sparse) //! * Vector -//! * Automatic derivatives +//! * Automatic differentiation (`Jet`) //! * Polynomial //! * DataFrame //! * Multinomial (not yet implemented) diff --git a/src/traits/mod.rs b/src/traits/mod.rs index 67a0d15..a3c5c15 100644 --- a/src/traits/mod.rs +++ b/src/traits/mod.rs @@ -1,3 +1,5 @@ +//! Shared trait definitions: mathematics, functional programming, mutability, pointers, and numeric abstractions + pub mod float; pub mod fp; pub mod general; diff --git a/src/util/mod.rs b/src/util/mod.rs index b39f296..97154d2 100644 --- a/src/util/mod.rs +++ b/src/util/mod.rs @@ -1,4 +1,4 @@ -//! Utility - plot, print, pickle and etc. +//! Utilities: constructors, printing, plotting, and low-level helpers pub mod api; pub mod non_macro;