matrices: doctest for matrix multiplication ordering.

rtchallenge/src/matrices.rs

@@ -1,10 +1,7 @@
 use std::fmt;
 use std::ops::{Index, IndexMut, Mul};
 
-use crate::tuples::Tuple;
-
-/// Value considered close enough for PartialEq implementations.
-const EPSILON: f32 = 0.00001;
+use crate::{tuples::Tuple, EPSILON};
 
 #[derive(Debug)]
 pub struct Matrix2x2 {
@@ -167,6 +164,36 @@ impl PartialEq for Matrix3x3 {
 #[derive(Copy, Clone, Default)]
 /// Matrix4x4 represents a 4x4 matrix in row-major form. So, element `m[i][j]` corresponds to m<sub>i,j</sub>
 /// where `i` is the row number and `j` is the column number.
+///
+/// # Examples
+/// ```
+/// use std::f32::consts::PI;
+///
+/// use rtchallenge::{matrices::Matrix4x4, tuples::Tuple};
+///
+/// // Individual transformations are applied in sequence.
+/// let p = Tuple::point(1., 0., 1.);
+/// let a = Matrix4x4::rotation_x(PI / 2.);
+/// let b = Matrix4x4::scaling(5., 5., 5.);
+/// let c = Matrix4x4::translate(10., 5., 7.);
+/// // Apply rotation first.
+/// let p2 = a * p;
+/// assert_eq!(p2, Tuple::point(1., -1., 0.));
+/// // Then apply scaling.
+/// let p3 = b * p2;
+/// assert_eq!(p3, Tuple::point(5., -5., 0.));
+/// // Then apply translation.
+/// let p4 = c * p3;
+/// assert_eq!(p4, Tuple::point(15., 0., 7.));
+///
+/// // Chained transformations must be applied in reverse order.
+/// let p = Tuple::point(1., 0., 1.);
+/// let a = Matrix4x4::rotation_x(PI / 2.);
+/// let b = Matrix4x4::scaling(5., 5., 5.);
+/// let c = Matrix4x4::translate(10., 5., 7.);
+/// let t = c * b * a;
+/// assert_eq!(t * p, Tuple::point(15., 0., 7.));
+/// ```
 pub struct Matrix4x4 {
     m: [[f32; 4]; 4],
 }