From af5e61136c1e78f7f62cf3360f86cc204a5b057a Mon Sep 17 00:00:00 2001
From: Bill Thiede <git@xinu.tv>
Date: Fri, 16 Jul 2021 16:51:55 -0700
Subject: [PATCH] matrices: doctest for matrix multiplication ordering.

---
 rtchallenge/src/matrices.rs | 35 +++++++++++++++++++++++++++++++----
 1 file changed, 31 insertions(+), 4 deletions(-)

diff --git a/rtchallenge/src/matrices.rs b/rtchallenge/src/matrices.rs
index d68fb80..8a0b8fe 100644
--- a/rtchallenge/src/matrices.rs
+++ b/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],
 }