From a89a5d70e8ce5c6b85336479c9f5700eb3074c2b Mon Sep 17 00:00:00 2001
From: Brendan Zabarauskas <bjzaba@yahoo.com.au>
Date: Tue, 3 Sep 2013 16:37:06 +1000
Subject: [PATCH] Documentation work

---
 src/cgmath/lib.rs        |  8 +++++++
 src/cgmath/matrix.rs     | 18 ++++++++++-----
 src/cgmath/point.rs      |  3 +++
 src/cgmath/projection.rs |  7 +-----
 src/cgmath/vector.rs     | 48 +++++++++++++++++++++++++++++-----------
 5 files changed, 59 insertions(+), 25 deletions(-)

diff --git a/src/cgmath/lib.rs b/src/cgmath/lib.rs
index fa11308..708b86e 100644
--- a/src/cgmath/lib.rs
+++ b/src/cgmath/lib.rs
@@ -29,3 +29,11 @@ pub mod quaternion;
 pub mod vector;
 
 pub mod projection;
+
+pub mod util {
+    use std::num::one;
+
+    /// This is horrific. We really need better from-int support in std::num.
+    #[inline]
+    pub fn two<T: Num>() -> T { one::<T>() + one::<T>() }
+}
diff --git a/src/cgmath/matrix.rs b/src/cgmath/matrix.rs
index 7dd76a5..fdc9aae 100644
--- a/src/cgmath/matrix.rs
+++ b/src/cgmath/matrix.rs
@@ -13,16 +13,24 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Column major, square matrix types and traits.
+
 use std::num::{one, zero};
 
 use array::*;
 use vector::*;
 
-#[deriving(Clone, Eq)] pub struct Mat2<S> { x: Vec2<S>, y: Vec2<S> }
-#[deriving(Clone, Eq)] pub struct Mat3<S> { x: Vec3<S>, y: Vec3<S>, z: Vec3<S> }
-#[deriving(Clone, Eq)] pub struct Mat4<S> { x: Vec4<S>, y: Vec4<S>, z: Vec4<S>, w: Vec4<S> }
+/// A 2 x 2, column major matrix
+#[deriving(Clone, Eq)]
+pub struct Mat2<S> { x: Vec2<S>, y: Vec2<S> }
 
-// Constructors
+/// A 3 x 3, column major matrix
+#[deriving(Clone, Eq)]
+pub struct Mat3<S> { x: Vec3<S>, y: Vec3<S>, z: Vec3<S> }
+
+/// A 4 x 4, column major matrix
+#[deriving(Clone, Eq)]
+pub struct Mat4<S> { x: Vec4<S>, y: Vec4<S>, z: Vec4<S>, w: Vec4<S> }
 
 impl<S: Clone + Num> Mat2<S> {
     #[inline]
@@ -123,8 +131,6 @@ impl<S: Clone + Num> Mat4<S> {
     }
 }
 
-// Trait impls
-
 array!(impl<S> Mat2<S> -> [Vec2<S>, ..2])
 array!(impl<S> Mat3<S> -> [Vec3<S>, ..3])
 array!(impl<S> Mat4<S> -> [Vec4<S>, ..4])
diff --git a/src/cgmath/point.rs b/src/cgmath/point.rs
index 7aeee90..7da336b 100644
--- a/src/cgmath/point.rs
+++ b/src/cgmath/point.rs
@@ -22,9 +22,11 @@ use std::num::zero;
 use array::*;
 use vector::*;
 
+/// A point in 2-dimensional space.
 #[deriving(Eq, Zero, Clone)]
 struct Point2<S> { x: S, y: S }
 
+/// A point in 2-dimensional space.
 #[deriving(Eq, Zero, Clone)]
 struct Point3<S> { x: S, y: S, z: S }
 
@@ -48,6 +50,7 @@ impl<S: Num> Point3<S> {
     pub fn origin() -> Point3<S> { zero() }
 }
 
+/// Specifies the numeric operations for point types.
 pub trait Point
 <
     S: Clone + Num,
diff --git a/src/cgmath/projection.rs b/src/cgmath/projection.rs
index 3868ea7..51c4652 100644
--- a/src/cgmath/projection.rs
+++ b/src/cgmath/projection.rs
@@ -16,12 +16,7 @@
 use std::num::{zero, one};
 
 use matrix::Mat4;
-
-/// Ick. We really need better from-int support in std::num.
-#[inline]
-fn two<T: Num>() -> T {
-    one::<T>() + one::<T>()
-}
+use util::two;
 
 /// Create a perspective projection matrix
 ///
diff --git a/src/cgmath/vector.rs b/src/cgmath/vector.rs
index ac69fdb..4f928a4 100644
--- a/src/cgmath/vector.rs
+++ b/src/cgmath/vector.rs
@@ -18,10 +18,19 @@ use std::num::{sqrt, atan2};
 
 use array::*;
 
-#[deriving(Eq, Clone, Zero)] pub struct Vec2<S> { x: S, y: S }
-#[deriving(Eq, Clone, Zero)] pub struct Vec3<S> { x: S, y: S, z: S }
-#[deriving(Eq, Clone, Zero)] pub struct Vec4<S> { x: S, y: S, z: S, w: S }
+/// A 2-dimensional vector.
+#[deriving(Eq, Clone, Zero)]
+pub struct Vec2<S> { x: S, y: S }
 
+/// A 3-dimensional vector.
+#[deriving(Eq, Clone, Zero)]
+pub struct Vec3<S> { x: S, y: S, z: S }
+
+/// A 4-dimensional vector.
+#[deriving(Eq, Clone, Zero)]
+pub struct Vec4<S> { x: S, y: S, z: S, w: S }
+
+// Utility macro for generating associated functions for the vectors
 macro_rules! vec(
     (impl $Self:ident <$S:ident> { $($field:ident),+ }) => (
         impl<$S: Clone + Num> $Self<$S> {
@@ -30,6 +39,12 @@ macro_rules! vec(
                 $Self { $($field: $field),+ }
             }
 
+            /// Construct a vector from a single value.
+            #[inline]
+            pub fn from_value(value: $S) -> $Self<$S> {
+                Array::build(|_| value.clone())
+            }
+
             /// The additive identity of the vector.
             #[inline]
             pub fn zero() -> $Self<$S> { $Self::from_value(zero()) }
@@ -37,12 +52,6 @@ macro_rules! vec(
             /// The additive identity of the vector.
             #[inline]
             pub fn ident() -> $Self<$S> { $Self::from_value(one()) }
-
-            /// Construct a vector from a single value.
-            #[inline]
-            pub fn from_value(value: $S) -> $Self<$S> {
-                Array::build(|_| value.clone())
-            }
         }
     )
 )
@@ -55,6 +64,9 @@ array!(impl<S> Vec2<S> -> [S, ..2])
 array!(impl<S> Vec3<S> -> [S, ..3])
 array!(impl<S> Vec4<S> -> [S, ..4])
 
+/// A trait that specifies a range of numeric operations for vectors. Not all
+/// of these make sense from a linear algebra point of view, but are included
+/// for pragmatic reasons.
 pub trait Vector
 <
     S: Clone + Num,
@@ -63,7 +75,9 @@ pub trait Vector
 :   Array<S, Slice>
 +   Neg<Self>
 {
-    #[inline] fn neg_self(&mut self) { for x in self.mut_iter() { *x = x.neg()   } }
+    // TODO: These method impls use iterators and higher order functions to
+    // provide generic impls for vector types of different dimensions. We
+    // need to check llvm's output to see how well it optimses these.
 
     #[inline] fn add_s(&self, s: S) -> Self { self.map(|x| x.add(&s)) }
     #[inline] fn sub_s(&self, s: S) -> Self { self.map(|x| x.sub(&s)) }
@@ -77,6 +91,8 @@ pub trait Vector
     #[inline] fn div_v(&self, other: &Self) -> Self { self.bimap(other, |a, b| a.div(b) ) }
     #[inline] fn rem_v(&self, other: &Self) -> Self { self.bimap(other, |a, b| a.rem(b) ) }
 
+    #[inline] fn neg_self(&mut self) { for x in self.mut_iter() { *x = x.neg() } }
+
     #[inline] fn add_self_s(&mut self, s: S) { for x in self.mut_iter() { *x = x.add(&s) } }
     #[inline] fn sub_self_s(&mut self, s: S) { for x in self.mut_iter() { *x = x.sub(&s) } }
     #[inline] fn mul_self_s(&mut self, s: S) { for x in self.mut_iter() { *x = x.mul(&s) } }
@@ -89,15 +105,19 @@ pub trait Vector
     #[inline] fn div_self_v(&mut self, other: &Self) { for (a, b) in self.mut_iter().zip(other.iter()) { *a = a.div(b) } }
     #[inline] fn rem_self_v(&mut self, other: &Self) { for (a, b) in self.mut_iter().zip(other.iter()) { *a = a.rem(b) } }
 
-    #[inline] fn comp_add(&self) -> S { self.iter().fold(zero::<S>(), |a, b| a.add(b)) }
-    #[inline] fn comp_mul(&self) -> S { self.iter().fold(one::<S>(),  |a, b| a.mul(b)) }
-
+    /// Vector dot product.
     #[inline]
     fn dot(&self, other: &Self) -> S {
         self.iter().zip(other.iter())
             .map(|(a, b)| a.mul(b))
             .fold(zero::<S>(), |a, b| a.add(&b))
     }
+
+    /// The sum of each component of the vector.
+    #[inline] fn comp_add(&self) -> S { self.iter().fold(zero::<S>(), |a, b| a.add(b)) }
+
+    /// The product of each component of the vector.
+    #[inline] fn comp_mul(&self) -> S { self.iter().fold(one::<S>(),  |a, b| a.mul(b)) }
 }
 
 impl<S: Clone + Num> Neg<Vec2<S>> for Vec2<S> { #[inline] fn neg(&self) -> Vec2<S> { self.map(|x| x.neg()) } }
@@ -128,6 +148,8 @@ impl<S: Clone + Num> Vec3<S> {
     }
 }
 
+/// Specifies geometric operations for vectors. This is only implemented for
+/// 2-dimensional and 3-dimensional vectors.
 pub trait EuclideanVector
 <
     S: Clone + Real + ApproxEq<S>,