From e321b1046b3837fed4ae8fa31c325b112640591f Mon Sep 17 00:00:00 2001
From: Brendan Zabarauskas <bjzaba@yahoo.com.au>
Date: Sun, 14 Jul 2013 14:43:29 +1000
Subject: [PATCH] Documentation work

---
 src/math/point.rs | 80 +++++++++++++++++++++++++++++++++--------------
 src/math/ray.rs   |  2 ++
 src/math/vec.rs   | 15 +++++++++
 3 files changed, 73 insertions(+), 24 deletions(-)

diff --git a/src/math/point.rs b/src/math/point.rs
index 6ac5807..1974176 100644
--- a/src/math/point.rs
+++ b/src/math/point.rs
@@ -29,7 +29,7 @@ use math::{Vec2, ToVec2, AsVec2};
 use math::{Vec3, ToVec3, AsVec3};
 use math::{Vec4, ToVec4};
 
-/// A geometric point
+/// A coordinate vector
 pub trait Point<T, Vec, Ray>: Eq
                             + Add<Vec, Self>
                             + Sub<Self, Vec>
@@ -44,7 +44,7 @@ pub trait Point<T, Vec, Ray>: Eq
     pub fn ray_to(&self, other: &Self) -> Ray;
 }
 
-/// A two-dimensional point
+/// A two-dimensional coordinate vector
 #[deriving(Clone, Eq)]
 pub struct Point2<T> { x: T, y: T }
 
@@ -72,16 +72,19 @@ impl<T:Clone + Num> AsPoint2<T> for Vec2<T> {
 }
 
 impl<T:Num> Point2<T> {
+    /// Creates a new point from three coordinates.
     #[inline]
     pub fn new(x: T, y: T) -> Point2<T> {
         Point2 { x: x, y: y }
     }
 
+    /// Converts a vector to a point.
     #[inline]
     pub fn from_vec2(vec: Vec2<T>) -> Point2<T> {
         unsafe { cast::transmute(vec) }
     }
 
+    /// The coordinate [0, 0].
     #[inline]
     pub fn origin() -> Point2<T> {
         Point2::new(zero!(T), zero!(T))
@@ -100,12 +103,14 @@ impl<T:Clone + Num> ToVec3<T> for Point2<T> {
 }
 
 impl<T:Clone + Float> Point2<T> {
+    /// Rotates a point around the `z` axis using a scalar angle.
     #[inline]
-    pub fn rotate_t(&self, radians: &T) -> Point2<T> {
+    pub fn rotate_z(&self, radians: &T) -> Point2<T> {
         Point2::new(self.x.cos() * (*radians),
                     self.y.sin() * (*radians))
     }
 
+    /// Applies a rotation to the point using a rotation matrix.
     #[inline]
     pub fn rotate_m(&self, mat: &Mat2<T>) -> Point2<T> {
         Point2::from_vec2(mat.mul_v(self.as_vec2()))
@@ -113,34 +118,41 @@ impl<T:Clone + Float> Point2<T> {
 }
 
 impl<T:Clone + Float> Point<T, Vec2<T>, Ray2<T>> for Point2<T> {
+    /// Applies a displacement vector to the point.
     #[inline]
     pub fn translate(&self, offset: &Vec2<T>) -> Point2<T> {
         (*self) + (*offset)
     }
 
+    /// Scales the distance from the point to the origin using the components
+    /// of a vector.
     #[inline]
     pub fn scale(&self, factor: &Vec2<T>) -> Point2<T> {
         (*self) * (*factor)
     }
 
+    /// Returns the squared distance from the point to `other`. This does not
+    /// perform a square root operation like in the `distance` method and can
+    /// therefore be more efficient for distance comparisons where the actual
+    /// distance is not needed.
     #[inline]
     pub fn distance2(&self, other: &Point2<T>) -> T {
         ((*other) - (*self)).magnitude2()
     }
 
-    /// Returns the scalar distance to the other point
+    /// Returns the scalar distance to the other point.
     #[inline]
     pub fn distance(&self, other: &Point2<T>) -> T {
         other.distance2(self).sqrt()
     }
 
-    /// Returns a normalized direction vector pointing to the other point
+    /// Returns a normalized direction vector pointing to the other point.
     #[inline]
     pub fn direction(&self, other: &Point2<T>) -> Vec2<T> {
         ((*other) - (*self)).normalize()
     }
 
-    /// Projects a normalized ray towards the other point
+    /// Projects a normalized ray towards the other point.
     #[inline]
     pub fn ray_to(&self, other: &Point2<T>) -> Ray2<T> {
         Ray2::new(self.clone(), self.direction(other))
@@ -148,13 +160,15 @@ impl<T:Clone + Float> Point<T, Vec2<T>, Ray2<T>> for Point2<T> {
 }
 
 impl<T:Num> Add<Vec2<T>, Point2<T>> for Point2<T> {
-    fn add(&self, other: &Vec2<T>) -> Point2<T> {
-        Point2::new(self.x + other.x,
-                    self.y + other.y)
+    /// Applies a displacement vector to the point.
+    fn add(&self, offset: &Vec2<T>) -> Point2<T> {
+        Point2::new(self.x + offset.x,
+                    self.y + offset.y)
     }
 }
 
 impl<T:Num> Sub<Point2<T>, Vec2<T>> for Point2<T> {
+    /// Calculates the displacement vector from the point to `other`.
     fn sub(&self, other: &Point2<T>) -> Vec2<T> {
         Vec2::new(self.x - other.x,
                   self.y - other.y)
@@ -162,9 +176,11 @@ impl<T:Num> Sub<Point2<T>, Vec2<T>> for Point2<T> {
 }
 
 impl<T:Num> Mul<Vec2<T>, Point2<T>> for Point2<T> {
-    fn mul(&self, scale: &Vec2<T>) -> Point2<T> {
-        Point2::new(self.x * scale.x,
-                    self.y * scale.y)
+    /// Scales the distance from the point to the origin using the components
+    /// of a vector.
+    fn mul(&self, factor: &Vec2<T>) -> Point2<T> {
+        Point2::new(self.x * factor.x,
+                    self.y * factor.y)
     }
 }
 
@@ -184,7 +200,7 @@ mod test_point2 {
     }
 }
 
-/// A three-dimensional point
+/// A three-dimensional coordinate vector
 #[deriving(Clone, Eq)]
 pub struct Point3<T> { x: T, y: T, z: T }
 
@@ -212,16 +228,19 @@ impl<T:Clone + Num> AsPoint3<T> for Vec3<T> {
 }
 
 impl<T:Num> Point3<T> {
+    /// Creates a new point from three coordinates.
     #[inline]
     pub fn new(x: T, y: T, z: T) -> Point3<T> {
         Point3 { x: x, y: y, z: z }
     }
 
+    /// Converts a vector to a point.
     #[inline]
     pub fn from_vec3(vec: Vec3<T>) -> Point3<T> {
         unsafe { cast::transmute(vec) }
     }
 
+    /// The coordinate [0, 0, 0].
     #[inline]
     pub fn origin() -> Point3<T> {
         Point3::new(zero!(T), zero!(T), zero!(T))
@@ -241,11 +260,13 @@ impl<T:Clone + Num> ToVec4<T> for Point3<T> {
 }
 
 impl<T:Clone + Float> Point3<T> {
+    /// Applies a rotation to the point using a quaternion.
     #[inline]
     pub fn rotate_q(&self, quat: &Quat<T>) -> Point3<T> {
         Point3::from_vec3(quat.mul_v(self.as_vec3()))
     }
 
+    /// Applies a rotation to the point using a rotation matrix.
     #[inline]
     pub fn rotate_m(&self, mat: &Mat3<T>) -> Point3<T> {
         Point3::from_vec3(mat.mul_v(self.as_vec3()))
@@ -253,34 +274,41 @@ impl<T:Clone + Float> Point3<T> {
 }
 
 impl<T:Clone + Float> Point<T, Vec3<T>, Ray3<T>> for Point3<T> {
+    /// Applies a displacement vector to the point.
     #[inline]
     pub fn translate(&self, offset: &Vec3<T>) -> Point3<T> {
         (*self) + (*offset)
     }
 
+    /// Scales the distance from the point to the origin using the components
+    /// of a vector.
     #[inline]
     pub fn scale(&self, factor: &Vec3<T>) -> Point3<T> {
         (*self) * (*factor)
     }
 
+    /// Returns the squared distance from the point to `other`. This does not
+    /// perform a square root operation like in the `distance` method and can
+    /// therefore be more efficient for distance comparisons where the actual
+    /// distance is not needed.
     #[inline]
     pub fn distance2(&self, other: &Point3<T>) -> T {
         ((*other) - (*self)).magnitude2()
     }
 
-    /// Returns the scalar distance to the other point
+    /// Returns the scalar distance to the other point.
     #[inline]
     pub fn distance(&self, other: &Point3<T>) -> T {
         other.distance2(self).sqrt()
     }
 
-    /// Returns a normalized direction vector pointing to the other point
+    /// Returns a normalized direction vector pointing to the other point.
     #[inline]
     pub fn direction(&self, other: &Point3<T>) -> Vec3<T> {
         ((*other) - (*self)).normalize()
     }
 
-    /// Projects a normalized ray towards the other point
+    /// Projects a normalized ray towards the other point.
     #[inline]
     pub fn ray_to(&self, other: &Point3<T>) -> Ray3<T> {
         Ray3::new(self.clone(), self.direction(other))
@@ -288,14 +316,16 @@ impl<T:Clone + Float> Point<T, Vec3<T>, Ray3<T>> for Point3<T> {
 }
 
 impl<T:Num> Add<Vec3<T>, Point3<T>> for Point3<T> {
-    fn add(&self, other: &Vec3<T>) -> Point3<T> {
-        Point3::new(self.x + other.x,
-                    self.y + other.y,
-                    self.z + other.z)
+    /// Applies a displacement vector to the point
+    fn add(&self, offset: &Vec3<T>) -> Point3<T> {
+        Point3::new(self.x + offset.x,
+                    self.y + offset.y,
+                    self.z + offset.z)
     }
 }
 
 impl<T:Num> Sub<Point3<T>, Vec3<T>> for Point3<T> {
+    /// Calculates the displacement required to move the point to `other`.
     fn sub(&self, other: &Point3<T>) -> Vec3<T> {
         Vec3::new(self.x - other.x,
                   self.y - other.y,
@@ -304,10 +334,12 @@ impl<T:Num> Sub<Point3<T>, Vec3<T>> for Point3<T> {
 }
 
 impl<T:Num> Mul<Vec3<T>, Point3<T>> for Point3<T> {
-    fn mul(&self, scale: &Vec3<T>) -> Point3<T> {
-        Point3::new(self.x * scale.x,
-                    self.y * scale.y,
-                    self.z * scale.z)
+    /// Scales the distance from the point to the origin using the components
+    /// of a vector.
+    fn mul(&self, factor: &Vec3<T>) -> Point3<T> {
+        Point3::new(self.x * factor.x,
+                    self.y * factor.y,
+                    self.z * factor.z)
     }
 }
 
diff --git a/src/math/ray.rs b/src/math/ray.rs
index c12d6f2..ec20eef 100644
--- a/src/math/ray.rs
+++ b/src/math/ray.rs
@@ -27,6 +27,7 @@ pub struct Ray2<T> {
 impl_approx!(Ray2 { origin, direction })
 
 impl<T> Ray2<T> {
+    /// Creates a new ray from a position coordinate and a direction vector
     #[inline]
     pub fn new(origin: Point2<T>, direction: Vec2<T>) -> Ray2<T> {
         Ray2 { origin: origin, direction: direction }
@@ -42,6 +43,7 @@ pub struct Ray3<T> {
 impl_approx!(Ray3 { origin, direction })
 
 impl<T> Ray3<T> {
+    /// Creates a new ray from a position coordinate and a direction vector
     #[inline]
     pub fn new(origin: Point3<T>, direction: Vec3<T>) -> Ray3<T> {
         Ray3 { origin: origin, direction: direction }
diff --git a/src/math/vec.rs b/src/math/vec.rs
index 11a5004..b829e25 100644
--- a/src/math/vec.rs
+++ b/src/math/vec.rs
@@ -153,21 +153,25 @@ impl<T:Clone + Num> ToVec3<T> for Vec2<T> {
 
 /// Constants for two-dimensional vectors.
 impl<T:Num> Vec2<T> {
+    /// Returns a two-dimensional vector with each component set to `1`.
     #[inline]
     pub fn identity() -> Vec2<T> {
         Vec2::new(one!(T), one!(T))
     }
 
+    /// Returns a two-dimensional vector with each component set to `0`.
     #[inline]
     pub fn zero() -> Vec2<T> {
         Vec2::new(zero!(T), zero!(T))
     }
 
+    /// Returns a zeroed two-dimensional vector with the `x` component set to `1`.
     #[inline]
     pub fn unit_x() -> Vec2<T> {
         Vec2::new(one!(T), zero!(T))
     }
 
+    /// Returns a zeroed two-dimensional vector with the `y` component set to `1`.
     #[inline]
     pub fn unit_y() -> Vec2<T> {
         Vec2::new(zero!(T), one!(T))
@@ -695,26 +699,31 @@ impl<T:Clone + Num> ToVec4<T> for Vec3<T> {
 
 /// Constants for three-dimensional vectors.
 impl<T:Num> Vec3<T> {
+    /// Returns a three-dimensional vector with each component set to `1`.
     #[inline]
     pub fn identity() -> Vec3<T> {
         Vec3::new(one!(T), one!(T), one!(T))
     }
 
+    /// Returns a three-dimensional vector with each component set to `0`.
     #[inline]
     pub fn zero() -> Vec3<T> {
         Vec3::new(zero!(T), zero!(T), zero!(T))
     }
 
+    /// Returns a zeroed three-dimensional vector with the `x` component set to `1`.
     #[inline]
     pub fn unit_x() -> Vec3<T> {
         Vec3::new(one!(T), zero!(T), zero!(T))
     }
 
+    /// Returns a zeroed three-dimensional vector with the `y` component set to `1`.
     #[inline]
     pub fn unit_y() -> Vec3<T> {
         Vec3::new(zero!(T), one!(T), zero!(T))
     }
 
+    /// Returns a zeroed three-dimensional vector with the `z` component set to `1`.
     #[inline]
     pub fn unit_z() -> Vec3<T> {
         Vec3::new(zero!(T), zero!(T), one!(T))
@@ -1291,31 +1300,37 @@ impl<T:Clone> Vec4<T> {
 
 /// Constants for four-dimensional vectors.
 impl<T:Num> Vec4<T> {
+    /// Returns a four-dimensional vector with each component set to `1`.
     #[inline]
     pub fn identity() -> Vec4<T> {
         Vec4::new(one!(T), one!(T), one!(T), one!(T))
     }
 
+    /// Returns a four-dimensional vector with each component set to `0`.
     #[inline]
     pub fn zero() -> Vec4<T> {
         Vec4::new(zero!(T), zero!(T), zero!(T), zero!(T))
     }
 
+    /// Returns a zeroed four-dimensional vector with the `x` component set to `1`.
     #[inline]
     pub fn unit_x() -> Vec4<T> {
         Vec4::new(one!(T), zero!(T), zero!(T), zero!(T))
     }
 
+    /// Returns a zeroed four-dimensional vector with the `y` component set to `1`.
     #[inline]
     pub fn unit_y() -> Vec4<T> {
         Vec4::new(zero!(T), one!(T), zero!(T), zero!(T))
     }
 
+    /// Returns a zeroed four-dimensional vector with the `z` component set to `1`.
     #[inline]
     pub fn unit_z() -> Vec4<T> {
         Vec4::new(zero!(T), zero!(T), one!(T), zero!(T))
     }
 
+    /// Returns a zeroed four-dimensional vector with the `w` component set to `1`.
     #[inline]
     pub fn unit_w() -> Vec4<T> {
         Vec4::new(zero!(T), zero!(T), zero!(T), one!(T))