Improve module doc comments

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};

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};

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

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;

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;

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

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;
 

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;
 

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".
 ///

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?)
 ///

core/src/render/cam.rs

@@ -1,3 +1,5 @@
+//! Cameras and camera transforms.
+
 use core::ops::Range;
 
 use crate::geom::{Tri, Vertex};

core/src/render/ctx.rs

@@ -1,11 +1,13 @@
+//! Rendering context and parameters.
+
 use core::cell::RefCell;
 use core::cmp::Ordering;
 
 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.

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;

core/src/util/rect.rs

@@ -1,3 +1,5 @@
+//! Rectangular regions.
+
 use core::fmt::Debug;
 use core::ops::{Bound::*, Range, RangeBounds, RangeFull, Sub};
 

front/src/wasm.rs

@@ -1,3 +1,5 @@
+//! Frontend using WebAssembly to render to a canvas element.
+
 #![allow(unused)]
 
 use core::cell::RefCell;

geom/src/solids.rs

@@ -1,5 +1,5 @@
 //! Mesh approximations of various geometric shapes.
-//!
+
 use core::array::from_fn;
 use core::ops::Range;