From 548991e0848992ba7a60db5099ed8488eeaf74d4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Johannes=20Dahlstr=C3=B6m?= <johannes.dahlstrom@gmail.com>
Date: Tue, 27 Aug 2024 17:15:43 +0300
Subject: [PATCH] Improve module doc comments

---
 core/src/lib.rs           | 1 +
 core/src/math/angle.rs    | 2 +-
 core/src/math/approx.rs   | 4 +++-
 core/src/math/color.rs    | 2 ++
 core/src/math/float.rs    | 8 ++++++++
 core/src/math/rand.rs     | 4 +++-
 core/src/math/space.rs    | 4 +++-
 core/src/math/vary.rs     | 6 ++++--
 core/src/math/vec.rs      | 8 +++++---
 core/src/render/batch.rs  | 4 +++-
 core/src/render/cam.rs    | 2 ++
 core/src/render/ctx.rs    | 4 +++-
 core/src/render/target.rs | 8 ++++----
 core/src/util/rect.rs     | 2 ++
 front/src/wasm.rs         | 2 ++
 geom/src/solids.rs        | 2 +-
 16 files changed, 47 insertions(+), 16 deletions(-)

diff --git a/core/src/lib.rs b/core/src/lib.rs
index 38f280d5..cac469fd 100644
--- a/core/src/lib.rs
+++ b/core/src/lib.rs
@@ -49,6 +49,7 @@ pub mod math;
 pub mod render;
 pub mod util;
 
+/// Prelude module exporting many frequently used items.
 pub mod prelude {
     #[cfg(feature = "fp")]
     pub use crate::math::mat::{rotate_x, rotate_y, rotate_z};
diff --git a/core/src/math/angle.rs b/core/src/math/angle.rs
index 105a925e..b823a7bb 100644
--- a/core/src/math/angle.rs
+++ b/core/src/math/angle.rs
@@ -1,4 +1,4 @@
-//! Angular quantities, including polar and spherical coordinate vectors.
+//! Angular quantities, including scalar angles and angular vectors.
 
 use core::f32::consts::{PI, TAU};
 use core::fmt::{self, Debug, Display};
diff --git a/core/src/math/approx.rs b/core/src/math/approx.rs
index 1bb6f77a..f602ff35 100644
--- a/core/src/math/approx.rs
+++ b/core/src/math/approx.rs
@@ -1,6 +1,8 @@
+//! Testing and asserting approximate equality.
+
 use core::iter::zip;
 
-/// Methods for testing the approximate equality of two values.
+/// Trait for testing approximate equality.
 ///
 /// Floating-point types are only an approximation of real numbers due to their
 /// finite precision. The presence of rounding errors means that two floats may
diff --git a/core/src/math/color.rs b/core/src/math/color.rs
index d1f28dc3..3c8c5850 100644
--- a/core/src/math/color.rs
+++ b/core/src/math/color.rs
@@ -1,3 +1,5 @@
+//! Colors and color spaces.
+
 use core::array;
 use core::fmt::{self, Debug, Formatter};
 use core::marker::PhantomData;
diff --git a/core/src/math/float.rs b/core/src/math/float.rs
index 3827f949..3f55bf39 100644
--- a/core/src/math/float.rs
+++ b/core/src/math/float.rs
@@ -1,3 +1,11 @@
+//! Floating-point compatibility API.
+//!
+//! Most floating-point functions are currently unavailable in `no_std`.
+//! This module provides the missing functions using either the `libm` or
+//! `micromath` crate, depending on which feature is enabled. As a fallback,
+//! it also implements a critical subset of the functions even if none of
+//! the features is enabled.
+
 #[cfg(feature = "libm")]
 pub mod libm {
     pub use libm::fabsf as abs;
diff --git a/core/src/math/rand.rs b/core/src/math/rand.rs
index 5addc5f2..0c64e26a 100644
--- a/core/src/math/rand.rs
+++ b/core/src/math/rand.rs
@@ -1,6 +1,8 @@
+//! Pseudo-random number generation and distributions.
+
 use core::{array, fmt::Debug, ops::Range};
 
-use crate::math::{Vec2, Vec3, Vector};
+use super::vec::{Vec2, Vec3, Vector};
 
 //
 // Traits and types
diff --git a/core/src/math/space.rs b/core/src/math/space.rs
index 896dcfb3..7e37f0d8 100644
--- a/core/src/math/space.rs
+++ b/core/src/math/space.rs
@@ -1,4 +1,6 @@
-//! Types and traits for representing linear (vector) and affine spaces.
+//! Linear (vector) spaces and affine spaces.
+//!
+//! TODO
 
 use core::marker::PhantomData;
 
diff --git a/core/src/math/vary.rs b/core/src/math/vary.rs
index 561aa2b1..5474d4ce 100644
--- a/core/src/math/vary.rs
+++ b/core/src/math/vary.rs
@@ -1,5 +1,7 @@
-//! Support for varyings: types that can be linearly interpolated across
-//! a face when rendering, such as colors, normals, or texture coordinates.
+//! Types that can be interpolated across a face when rendering.
+//!
+//! Common varying types include colors, texture coordinates,
+//! and vertex normals.
 
 use core::mem;
 
diff --git a/core/src/math/vec.rs b/core/src/math/vec.rs
index be2ea809..c5432ebc 100644
--- a/core/src/math/vec.rs
+++ b/core/src/math/vec.rs
@@ -1,3 +1,5 @@
+//! Real and projective vectors.
+//!
 //! TODO
 
 use core::array;
@@ -50,17 +52,17 @@ pub type Vec2u<Basis = ()> = Vector<[u32; 2], Real<2, Basis>>;
 // Free functions
 //
 
-/// Returns a 2D Euclidean vector with components `x` and `y`.
+/// Returns a real 2-vector with components `x` and `y`.
 pub const fn vec2<Sc, B>(x: Sc, y: Sc) -> Vector<[Sc; 2], Real<2, B>> {
     Vector([x, y], PhantomData)
 }
 
-/// Returns a 3D Euclidean vector with components `x`, `y`, and `z`.
+/// Returns a real 3-vector with components `x`, `y`, and `z`.
 pub const fn vec3<Sc, B>(x: Sc, y: Sc, z: Sc) -> Vector<[Sc; 3], Real<3, B>> {
     Vector([x, y, z], PhantomData)
 }
 
-/// Returns a vector with all components equal to the argument.
+/// Returns a vector with all components equal to a scalar.
 ///
 /// This operation is also called "broadcast".
 ///
diff --git a/core/src/render/batch.rs b/core/src/render/batch.rs
index a228e617..9de94c1e 100644
--- a/core/src/render/batch.rs
+++ b/core/src/render/batch.rs
@@ -1,3 +1,5 @@
+//! Builder for setting up geometry for rendering.
+
 use alloc::vec::Vec;
 use core::borrow::Borrow;
 
@@ -13,7 +15,7 @@ use super::{ctx::Context, target::Target, NdcToScreen, Shader};
 /// * [faces][Batch::faces]: A list of triangles, each a triplet of indices
 ///   into the list of vertices (TODO: handling oob)
 /// * [vertices][Batch::vertices]: A list of vertices
-/// * [shader][Batch::shaders]: The combined vertex and fragment shader used
+/// * [shader][Batch::shader]: The combined vertex and fragment shader used
 /// * [target][Batch::target]: The render target to render into
 /// * [context][Batch::context]: The rendering context and settings used. (TODO: optional?)
 ///
diff --git a/core/src/render/cam.rs b/core/src/render/cam.rs
index 7fd6bacc..67558223 100644
--- a/core/src/render/cam.rs
+++ b/core/src/render/cam.rs
@@ -1,3 +1,5 @@
+//! Cameras and camera transforms.
+
 use core::ops::Range;
 
 use crate::geom::{Tri, Vertex};
diff --git a/core/src/render/ctx.rs b/core/src/render/ctx.rs
index cdb4185a..4953dbc7 100644
--- a/core/src/render/ctx.rs
+++ b/core/src/render/ctx.rs
@@ -1,3 +1,5 @@
+//! Rendering context and parameters.
+
 use core::cell::RefCell;
 use core::cmp::Ordering;
 
@@ -5,7 +7,7 @@ use crate::math::color::{rgba, Color4};
 
 use super::stats::Stats;
 
-/// Rendering context.
+/// Context and parameters used by the renderer.
 #[derive(Clone, Debug)]
 pub struct Context {
     /// The color with which to fill the color buffer to clear it, if any.
diff --git a/core/src/render/target.rs b/core/src/render/target.rs
index e57a1246..502f7260 100644
--- a/core/src/render/target.rs
+++ b/core/src/render/target.rs
@@ -1,8 +1,8 @@
-//! Render targets.
+//! Render targets such as framebuffers.
 //!
-//! The typical render target is a framebuffer, comprising a color buffer,
-//! depth buffer, and possible auxiliary buffers. Special render targets can
-//! be used, for example, for visibility or occlusion computations.
+//! The typical render target comprises a color buffer, depth buffer,
+//! and possible auxiliary buffers. Special render targets can be used,
+//! for example, for visibility or occlusion computations.
 
 use crate::math::vary::Vary;
 use crate::util::buf::AsMutSlice2;
diff --git a/core/src/util/rect.rs b/core/src/util/rect.rs
index 7d1281f8..53d5f6fc 100644
--- a/core/src/util/rect.rs
+++ b/core/src/util/rect.rs
@@ -1,3 +1,5 @@
+//! Rectangular regions.
+
 use core::fmt::Debug;
 use core::ops::{Bound::*, Range, RangeBounds, RangeFull, Sub};
 
diff --git a/front/src/wasm.rs b/front/src/wasm.rs
index f490f75c..a7ee0240 100644
--- a/front/src/wasm.rs
+++ b/front/src/wasm.rs
@@ -1,3 +1,5 @@
+//! Frontend using WebAssembly to render to a canvas element.
+
 #![allow(unused)]
 
 use core::cell::RefCell;
diff --git a/geom/src/solids.rs b/geom/src/solids.rs
index 2034a20b..eb3382a5 100644
--- a/geom/src/solids.rs
+++ b/geom/src/solids.rs
@@ -1,5 +1,5 @@
 //! Mesh approximations of various geometric shapes.
-//!
+
 use core::array::from_fn;
 use core::ops::Range;