Improve documentation

src/mat.rs

@@ -15,48 +15,127 @@ use quat::{Quat, ToQuat};
 use vec::{NumericVector, Vec2, Vec3, Vec4};
 
 /**
- * An N x N Matrix
+ * The base square matrix trait
  */
 pub trait Matrix<T,V>: Dimensional<V>, ToPtr<T>, Eq, Neg<self> {
+    /**
+     * Returns the column vector at `i`
+     */
     pure fn col(&self, i: uint) -> V;
+    
+    /**
+     * Returns the row vector at `i`
+     */
     pure fn row(&self, i: uint) -> V;
     
+    /**
+     * Returns the identity matrix
+     */
     static pure fn identity() -> self;
+    
+    /**
+     * Returns a matrix with all elements set to zero
+     */
     static pure fn zero() -> self;
     
+    /**
+     * Returns the scalar multiplication of this matrix and `value`
+     */
     pure fn mul_t(&self, value: T) -> self;
+    
+    /**
+     * Returns the matrix vector product of the matrix and `vec`
+     */
     pure fn mul_v(&self, vec: &V) -> V;
+    
+    /**
+     * Ruturns the matrix addition of the matrix and `other`
+     */
     pure fn add_m(&self, other: &self) -> self;
+    
+    /**
+     * Ruturns the difference between the matrix and `other`
+     */
     pure fn sub_m(&self, other: &self) -> self;
     
+    /**
+     * Returns the matrix product of the matrix and `other`
+     */
     pure fn mul_m(&self, other: &self) -> self;
+    
+    /**
+     * Returns the matrix dot product of the matrix and `other`
+     */
     pure fn dot(&self, other: &self) -> T;
     
+    /**
+     * Returns the determinant of the matrix
+     */
     pure fn determinant(&self) -> T;
+    
+    /**
+     * Returns the sum of the main diagonal of the matrix
+     */
     pure fn trace(&self) -> T;
     
+    /**
+     * Returns the inverse of the matrix
+     */
     pure fn inverse(&self) -> Option<self>;
+    
+    /**
+     * Returns the transpose of the matrix
+     */
     pure fn transpose(&self) -> self;
     
+    /**
+     * Returns `true` if the matrix is approximately equal to the
+     * identity matrix
+     */
     pure fn is_identity(&self) -> bool;
+    
+    /**
+     * Returns `true` all the elements outside the main diagonal are
+     * approximately equal to zero.
+     */
     pure fn is_diagonal(&self) -> bool;
+    
+    /**
+     * Returns `true` if the matrix is not approximately equal to the
+     * identity matrix.
+     */
     pure fn is_rotated(&self) -> bool;
+    
+    /**
+     * Returns `true` if the matrix is approximately symmetrical (ie, if the
+     * matrix is equal to its transpose).
+     */
     pure fn is_symmetric(&self) -> bool;
+    
+    /**
+     * Returns `true` if  the matrix is invertable
+     */
     pure fn is_invertible(&self) -> bool;
 }
 
-/// A 2 x 2 square matrix with numeric elements
+/**
+ * A 2 x 2 square matrix with numeric elements
+ */
 pub trait Matrix2<T,V>: Matrix<T,V> {
     pure fn to_mat3(&self) -> Mat3<T>;
     pure fn to_mat4(&self) -> Mat4<T>;
 }
 
-/// A 3 x 3 square matrix with numeric elements
+/**
+ * A 3 x 3 square matrix with numeric elements
+ */
 pub trait Matrix3<T,V>: Matrix<T,V> {
     pure fn to_mat4(&self) -> Mat4<T>;
 }
 
-/// A 4 x 4 square matrix with numeric elements
+/**
+ * A 4 x 4 square matrix with numeric elements
+ */
 pub trait Matrix4<T,V>: Matrix<T,V> {
 }
 

src/quat.rs

@@ -15,34 +15,89 @@ use num::kinds::{Float, Number};
 use vec::Vec3;
 
 
-///
+/**
-/// The base quaternion trait
+ * The base quaternion trait
-///
+ */
-    static pure fn identity() -> self;      /// The multiplicative identity
-    static pure fn zero() -> self;          /// The additive identity
 pub trait Quaternion<T>: Dimensional<T>, ToPtr<T>, Eq, Neg<self> {
+    /**
+     * Returns the multiplicative identity, ie: `q = 1 + 0i + 0j + 0i`
+     */
+    static pure fn identity() -> self;
     
+    /**
+     * Returns the additive identity, ie: `q = 0 + 0i + 0j + 0i`
+     */
+    static pure fn zero() -> self;
+    
+    /**
+     * Returns the result of multiplying the quaternion a scalar
+     */
     pure fn mul_t(&self, value: T) -> self;
+    
+    /**
+     * Returns the result of dividing the quaternion a scalar
+     */
     pure fn div_t(&self, value: T) -> self;
     
+    /**
+     * Returns the result of multiplying the quaternion by a vector
+     */
     pure fn mul_v(&self, vec: &Vec3<T>) -> Vec3<T>;
     
+    /**
+     * Returns the sum of this quaternion and `other` 
+     */
     pure fn add_q(&self, other: &self) -> self;
+    
+    /**
+     * Returns the sum of this quaternion and `other` 
+     */
     pure fn sub_q(&self, other: &self) -> self;
+    
+    /**
+     * Returns the the result of multipliplying the quaternion by `other`
+     */
     pure fn mul_q(&self, other: &self) -> self;
     
+    /**
+     * The dot product of the quaternion and `other`
+     */
     pure fn dot(&self, other: &self) -> T;
     
     pure fn conjugate(&self) -> self;
+    
+    /**
+     * Returns the multiplicative inverse of the quaternion
+     */
     pure fn inverse(&self) -> self;
     pure fn length2(&self) -> T;
     pure fn length(&self) -> T;
+    
+    /**
+     * Returns the normalized quaternion
+     */
     pure fn normalize(&self) -> self;
     
+    /**
+     * Normalised linear interpolation
+     */
     pure fn nlerp(&self, other: &self, amount: T) -> self;
+    
+    /**
+     * Perform a spherical linear interpolation between the quaternion and
+     * `other`. This is more accutrate than `nlerp`, but is also more
+     * computationally intensive.
+     */ 
     pure fn slerp(&self, other: &self, amount: T) -> self;
     
+    /**
+     * Convert the quaternion to a 3 x 3 rotation matrix
+     */
     pure fn to_mat3(&self) -> Mat3<T>;
+    
+    /**
+     * Convert the quaternion to a 4 x 4 transformation matrix
+     */
     pure fn to_mat4(&self) -> Mat4<T>;
 }
 
@@ -58,11 +113,18 @@ pub trait ToQuat<T> {
 pub struct Quat<T> { s: T, v: Vec3<T> }
 
 pub impl<T> Quat<T> {
+    /**
+     * Construct the quaternion from one scalar component and three
+     * imaginary components
+     */
     #[inline(always)]
     static pure fn new(s: T, vx: T, vy: T, vz: T) -> Quat<T> {
         Quat::from_sv(move s, move Vec3::new(move vx, move vy, move vz))
     }
     
+    /**
+     * Construct the quaternion from a scalar and a vector
+     */
     #[inline(always)]
     static pure fn from_sv(s: T, v: Vec3<T>) -> Quat<T> {
         Quat { s: move s, v: move v }

src/vec.rs

@@ -12,7 +12,7 @@ use num::default_eq::DefaultEq;
 use num::kinds::Number;
 
 /**
- * The base vector trait
+ * The base generic vector trait
  */
 pub trait Vector<T>: Dimensional<T>, ToPtr<T>, Eq, DefaultEq {
     /// Construct the vector from a single value, copying it to each component
@@ -65,17 +65,17 @@ pub trait NumericVector<T>: Vector<T>, Neg<self>{
     pure fn div_t(&self, value: T) -> self;
     
     /**
-     * Returns the sum of this vector with `other`
+     * Returns the sum of the vector with `other`
      */
     pure fn add_v(&self, other: &self) -> self;
     
     /**
-     * Returns the difference between this vector and `other`
+     * Returns the difference between the vector and `other`
      */
     pure fn sub_v(&self, other: &self) -> self;
     
     /**
-     * Returns the dot product of this vector and `other`
+     * Returns the dot product of the vector and `other`
      */
     pure fn dot(&self, other: &self) -> T;
 }
@@ -84,19 +84,19 @@ pub trait NumericVector<T>: Vector<T>, Neg<self>{
  * A 2-dimensional vector with numeric components
  */
 pub trait NumericVector2<T>: NumericVector<T> {
-//     static pure fn unit_x() -> self;
+    // static pure fn unit_x() -> self;
-//     static pure fn unit_y() -> self;
+    // static pure fn unit_y() -> self;
 }
 
 /**
  * A 3-dimensional vector with numeric components
  */
 pub trait NumericVector3<T>: NumericVector<T> {
-//     static pure fn unit_x() -> self;
+    // static pure fn unit_x() -> self;
-//     static pure fn unit_y() -> self;
+    // static pure fn unit_y() -> self;
-//     static pure fn unit_z() -> self;
+    // static pure fn unit_z() -> self;
     /**
-     * Returns the cross product of this vector and `other`
+     * Returns the cross product of the vector and `other`
      */
     pure fn cross(&self, other: &self) -> self;
 }
@@ -105,10 +105,10 @@ pub trait NumericVector3<T>: NumericVector<T> {
  * A 4-dimensional vector with numeric components
  */
 pub trait NumericVector4<T>: NumericVector<T> {
-//     static pure fn unit_x() -> self;
+    // static pure fn unit_x() -> self;
-//     static pure fn unit_y() -> self;
+    // static pure fn unit_y() -> self;
-//     static pure fn unit_z() -> self;
+    // static pure fn unit_z() -> self;
-//     static pure fn unit_w() -> self;
+    // static pure fn unit_w() -> self;
 }
 
 /**
@@ -116,7 +116,7 @@ pub trait NumericVector4<T>: NumericVector<T> {
  */
 pub trait GeometricVector<T>: NumericVector<T> {
     /**
-     * Returns the squared length of this vector
+     * Returns the squared length of the vector
      */
     pure fn length2(&self) -> T;
     
@@ -126,22 +126,22 @@ pub trait GeometricVector<T>: NumericVector<T> {
     pure fn length(&self) -> T;
     
     /**
-     * Returns the distance between this vector and `other`
+     * Returns the squared distance between the vector and `other`.
      */
     pure fn distance2(&self, other: &self) -> T;
     
     /**
-     * Returns the squared distance between this vector and `other`
+     * Returns the distance between the vector and `other`
      */
     pure fn distance(&self, other: &self) -> T;
     
     /**
-     * Returns this vector normalized
+     * Returns the normalized vector
      */
     pure fn normalize(&self) -> self;
     
     /**
-     * Linearly intoperlate between the vector and `other` by `amount`
+     * Linearly intoperlate between the vector and `other`
      */
     pure fn lerp(&self, other: &self, amount: T) -> self;
 }