Update documentation of fj-math

fj-math/src/coordinates.rs

@@ -3,20 +3,29 @@ use super::Scalar;
 /// 1-dimensional curve coordinates
 #[repr(C)]
 pub struct T {
+    /// The single coordinate of the 1-dimensional curve coordinates
     pub t: Scalar,
 }
 
 /// 2-dimensional surface coordinates
 #[repr(C)]
 pub struct Uv {
+    /// The first coordinate of the 2-dimensional surface coordinates
     pub u: Scalar,
+
+    /// The second coordinate of the 2-dimensional surface coordinates
     pub v: Scalar,
 }
 
 /// 3-dimensional model coordinates
 #[repr(C)]
 pub struct Xyz {
+    /// The first coordinate of the 3-dimensional model coordinates
     pub x: Scalar,
+
+    /// The second coordinate of the 3-dimensional model coordinates
     pub y: Scalar,
+
+    /// The third coordinate of the 3-dimensional model coordinates
     pub z: Scalar,
 }

fj-math/src/lib.rs

@@ -1,3 +1,30 @@
+//! Math primitives for the Fornjot ecosystem
+//!
+//! This crates provides basic math types for the Fornjot ecosystem. It is built
+//! on [nalgebra] and [Parry], but provides an interface that is specifically
+//! tailored to the needs of Fornjot.
+//!
+//! # Failing [`From`]/[`Into`] implementations
+//!
+//! Please note that any [`From`]/[`Into`] implementation that convert floating
+//! point numbers into [`Scalar`] can panic. These conversions call
+//! [`Scalar::from_f64`] internally and panic under the same conditions. This
+//! affects [`Scalar`] itself, but also any other types in this crate that
+//! provide conversions from types that involve `f64`.
+//!
+//! This explicitly goes against the mandate of [`From`]/[`Into`], whose
+//! documentation states that implementations must not fail. This is a
+//! deliberate design decision. The intended use case of `Scalar` is math code
+//! that considers NaN results a bug, not a recoverable error.
+//!
+//! For this use case, having easy conversions available is an advantage, and
+//! explicit `unwrap`/`expect` calls would add nothing. In addition, the
+//! [`From`]/[`Into`] documentation fails to provide any reasons for its
+//! mandate.
+//!
+//! [nalgebra]: https://nalgebra.org/
+//! [Parry]: https://www.parry.rs/
+
 mod aabb;
 mod coordinates;
 mod point;

fj-math/src/point.rs

@@ -7,9 +7,11 @@ use super::{
 
 /// An n-dimensional point
 ///
-/// The dimensionality is defined by the const generic argument `D`.
+/// The dimensionality of the point is defined by the const generic `D`
+/// parameter.
 #[derive(Clone, Copy, Eq, PartialEq, Hash, Ord, PartialOrd)]
 pub struct Point<const D: usize> {
+    /// The coordinates of the point
     pub coords: Vector<D>,
 }
 

fj-math/src/scalar.rs

@@ -8,23 +8,6 @@ use decorum::R64;
 /// value is not NaN. This allows `Scalar` to provide implementations of [`Eq`],
 /// [`Ord`], and [`Hash`], enabling `Scalar` (and types built on top of it), to
 /// be used as keys in hash maps, hash sets, and similar types.
-///
-/// # Failing `From`/`Into` implementations
-///
-/// Please note that the [`From`]/[`Into`] implementation that convert floating
-/// point numbers into `Scalar` can panic. These conversions call
-/// [`Scalar::from_f64`] internally and panic under the same conditions.
-///
-/// This explicitly goes against the mandate of [`From`]/[`Into`], whose
-/// documentation mandate that implementations must not fail. This is a
-/// deliberate design decision. The intended use case of `Scalar` is math code
-/// that considers non-finite floating point values a bug, not a recoverable
-/// error.
-///
-/// For this use case, having easy conversions available is an advantage, and
-/// explicit `unwrap`/`expect` calls would add nothing. In addition, the mandate
-/// not to fail is not motivated in any way, in the [`From`]/[`Into`]
-/// documentation.
 #[derive(Clone, Copy)]
 pub struct Scalar(f64);
 
@@ -46,6 +29,8 @@ impl Scalar {
 
     /// Construct a `Scalar` from an `f64`
     ///
+    /// # Panics
+    ///
     /// Panics, if `scalar` is NaN.
     pub fn from_f64(scalar: f64) -> Self {
         if scalar.is_nan() {

fj-math/src/segment.rs

@@ -3,6 +3,9 @@ use std::fmt;
 use super::Point;
 
 /// A line segment, defined by its two end points
+///
+/// The dimensionality of the segment is defined by the const generic `D`
+/// parameter.
 #[derive(Clone, Copy, Eq, PartialEq, Hash, Ord, PartialOrd)]
 pub struct Segment<const D: usize> {
     a: Point<D>,

fj-math/src/triangle.rs

@@ -1,6 +1,9 @@
 use super::{Point, Scalar};
 
 /// A triangle
+///
+/// The dimensionality of the triangle is defined by the const generic `D`
+/// parameter.
 #[derive(Clone, Copy, Debug, Eq, PartialEq, Hash, Ord, PartialOrd)]
 pub struct Triangle<const D: usize> {
     points: [Point<D>; 3],

fj-math/src/vector.rs

@@ -7,7 +7,8 @@ use super::{
 
 /// An n-dimensional vector
 ///
-/// The dimensionality is defined by the const generic argument `D`.
+/// The dimensionality of the vector is defined by the const generic `D`
+/// parameter.
 #[derive(Clone, Copy, Eq, PartialEq, Hash, Ord, PartialOrd)]
 pub struct Vector<const D: usize> {
     /// The vector components
@@ -15,7 +16,12 @@ pub struct Vector<const D: usize> {
 }
 
 impl<const D: usize> Vector<D> {
-    /// Construct a `Vector` from an array
+    /// Construct a `Vector` from `f64` components
+    ///
+    /// # Panics
+    ///
+    /// Panics, if the components can not be converted to [`Scalar`]. See
+    /// [`Scalar::from_f64`], which this method uses internally.
     pub fn from_components_f64(components: [f64; D]) -> Self {
         Self {
             components: components.map(Scalar::from_f64),