More documentation updates

src/color/color.rs

@@ -15,7 +15,9 @@ use num::kinds::{Float, Number};
  */
 pub trait Color<T>: Dimensional<T>, ToPtr<T>, Eq {
     /**
-     * Returns the color with each component inverted
+     * # Return value
+     *
+     * The color with each component inverted
      */
     pure fn inverse(&self) -> self;
     
@@ -30,7 +32,7 @@ pub trait Color<T>: Dimensional<T>, ToPtr<T>, Eq {
     pure fn to_rgb_u8(&self) -> RGB<u8>;
     
     /**
-     * Convert the color to a RGB<u16>
+     * Convert the color to a `RGB<u16>`
      *
      * # Returns
      *
@@ -144,6 +146,7 @@ pub trait Color4<T>: Color<T> {
     pure fn to_hsva_f64(&self) -> HSVA<f64>;
 }
 
+// TODO!!!
 // pub trait ColorRGB<T> {
 //     static pure fn from_hex(hex: u8) -> self;
 // }
@@ -221,7 +224,20 @@ pub pure fn to_rgb<T:Copy Float Sign>(color: &HSV<T>) -> RGB<T> {
 
 
 
-
+/**
+ *  A RGB color type (red, green, blue)
+ *
+ * # Type parameters
+ *
+ * * `T` - A color component which should be one of the following primitive
+ *         types: `u8`, `u16`, `u32`, `u64`, `f32` or `f64`.
+ *
+ * # Fields
+ *
+ * * `r` - the red component
+ * * `g` - the green component
+ * * `b` - the blue component
+ */
 pub struct RGB<T> { r: T, g: T, b: T }
 
 pub impl<T:Copy> RGB<T> {
@@ -364,8 +380,21 @@ pub impl<T:Copy Eq> RGB<T>: Eq {
 
 
 
-
+/**
-
+ *  A RGBA color type (red, green, blue, alpha)
+ *
+ * # Type parameters
+ *
+ * * `T` - A color component which should be one of the following primitive
+ *         types: `u8`, `u16`, `u32`, `u64`, `f32` or `f64`.
+ *
+ * # Fields
+ *
+ * * `r` - the red component
+ * * `g` - the green component
+ * * `b` - the blue component
+ * * `a` - the alpha component
+ */
 pub struct RGBA<T> { r: T, g: T, b: T, a: T }
 
 pub impl<T:Copy> RGBA<T> {
@@ -517,9 +546,19 @@ pub impl<T:Copy Eq> RGBA<T>: Eq {
 
 
 
-
+/**
-
+ *  A HSV color type (hue, saturation, value)
-
+ *
+ * # Type parameters
+ *
+ * * `T` - A color component which should be either an `f32` or `f64`.
+ *
+ * # Fields
+ *
+ * * `h` - the hue component in degrees (from 0.0 to 360.0)
+ * * `s` - the saturation component
+ * * `v` - the value (brightness) component
+ */
 pub struct HSV<T> { h: Degrees<T>, s: T, v: T }
 
 pub impl<T:Copy> HSV<T> {
@@ -638,8 +677,20 @@ pub impl<T:Copy Float> HSV<T>: Eq {
 
 
 
-
+/**
-
+ *  A HSVA color type (hue, saturation, value, alpha)
+ *
+ * # Type parameters
+ *
+ * * `T` - A color component which should be either an `f32` or `f64`.
+ *
+ * # Fields
+ *
+ * * `h` - the hue component in degrees (from 0.0 to 360.0)
+ * * `s` - the saturation component
+ * * `v` - the value (brightness) component
+ * * `v` - the alpha component
+ */
 pub struct HSVA<T> { h: Degrees<T>, s: T, v: T, a: T }
 
 pub impl<T:Copy> HSVA<T> {

src/mat.rs

@@ -26,62 +26,86 @@ use vec::{NumericVector, Vec2, Vec3, Vec4};
  */
 pub trait Matrix<T,V>: Dimensional<V>, ToPtr<T>, Eq, Neg<self> {
     /**
-     * Returns the column vector at `i`
+     * # Return value
+     *
+     * The column vector at `i`
      */
     pure fn col(&self, i: uint) -> V;
     
     /**
-     * Returns the row vector at `i`
+     * # Return value
+     *
+     * The row vector at `i`
      */
     pure fn row(&self, i: uint) -> V;
     
     /**
-     * Returns the identity matrix
+     * # Return value
+     *
+     * The identity matrix
      */
     static pure fn identity() -> self;
     
     /**
-     * Returns a matrix with all elements set to zero
+     * # Return value
+     *
+     * A matrix with all elements set to zero
      */
     static pure fn zero() -> self;
     
     /**
-     * Returns the scalar multiplication of this matrix and `value`
+     * # Return value
+     *
+     * 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`
+     * # Return value
+     *
+     * 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`
+     * # Return value
+     *
+     * The matrix addition of the matrix and `other`
      */
     pure fn add_m(&self, other: &self) -> self;
     
     /**
-     * Ruturns the difference between the matrix and `other`
+     * # Return value
+     *
+     * The difference between the matrix and `other`
      */
     pure fn sub_m(&self, other: &self) -> self;
     
     /**
-     * Returns the matrix product of the matrix and `other`
+     * # Return value
+     *
+     * 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`
+     * # Return value
+     *
+     * The matrix dot product of the matrix and `other`
      */
     pure fn dot(&self, other: &self) -> T;
     
     /**
-     * Returns the determinant of the matrix
+     * # Return value
+     *
+     * The determinant of the matrix
      */
     pure fn determinant(&self) -> T;
     
     /**
-     * Returns the sum of the main diagonal of the matrix
+     * # Return value
+     *
+     * The sum of the main diagonal of the matrix
      */
     pure fn trace(&self) -> T;
     
@@ -90,42 +114,61 @@ pub trait Matrix<T,V>: Dimensional<V>, ToPtr<T>, Eq, Neg<self> {
      * 
      * # Return value
      *
-     * - `Some(m)` if the inversion was successful, where `m` is the inverted matrix
+     * * `Some(m)` - if the inversion was successful, where `m` is the inverted matrix
-     * - `None` if the inversion was unsuccessful (because the matrix was not invertable)
+     * * `None` - if the inversion was unsuccessful (because the matrix was not invertable)
      */
     pure fn inverse(&self) -> Option<self>;
     
     /**
-     * Returns the transpose of the matrix
+     * # Return value
+     *
+     * The transposed matrix
      */
     pure fn transpose(&self) -> self;
     
     /**
-     * Returns `true` if the matrix is approximately equal to the
+     * Check to see if the matrix is an identity matrix
-     * identity matrix
+     *
+     * # Return value
+     * 
+     * `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
+     * Check to see if the matrix is diagonal
-     * approximately equal to zero.
+     *
+     * # Return value
+     *
+     * `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
+     * Check to see if the matrix is rotated
-     * identity matrix.
+     *
+     * # Return value
+     *
+     * `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
+     * Check to see if the matrix is symmetric
-     * matrix is equal to its transpose).
+     *
+     * # Return value
+     *
+     * `true` if the matrix is approximately equal to its transpose).
      */
     pure fn is_symmetric(&self) -> bool;
     
     /**
-     * Returns `true` if  the matrix is invertable
+     * Check to see if the matrix is invertable
+     *
+     * # Return value
+     *
+     * `true` if  the matrix is invertable
      */
     pure fn is_invertible(&self) -> bool;
 }
@@ -135,7 +178,9 @@ pub trait Matrix<T,V>: Dimensional<V>, ToPtr<T>, Eq, Neg<self> {
  */
 pub trait MutableMatrix<T,V>: Matrix<T,V> {
     /**
-     * Get a mutable reference to the column at `i`
+     * # Return value
+     *
+     * A mutable reference to the column at `i`
      */
     fn col_mut(&mut self, i: uint) -> &self/mut V;
     

src/num/kinds.rs

@@ -7,7 +7,22 @@ use num::default_eq::DefaultEq;
 
 pub trait Number: DefaultEq, Eq, Num, NumConv, Ord {
     /**
-     * Construct a number from the type `T:Number`
+     * Cast a number to the type surrounding the static method
+     *
+     * # Type parameters
+     *
+     * `T` - The type of the number which will be cast.
+     *
+     * # Return value
+     *
+     * `n` cast to the type surrounding the static method
+     *
+     * # Example
+     *
+     * ~~~
+     * let twenty: f32 = Number::from(0x14);
+     * assert twenty == 20f32;
+     * ~~~
      */
     static pure fn from<T:Number>(n: T) -> self;
     

src/quat.rs

@@ -1,3 +1,12 @@
+/**
+ * > Every morning in the early part of October 1843, on my coming down to
+ *   breakfast, your brother William Edward and yourself used to ask me: "Well,
+ *   Papa, can you multiply triples?" Whereto I was always obliged to reply,
+ *   with a sad shake of the head, "No, I can only add and subtract them."
+ *
+ *   Sir William Hamilton
+ */
+
 use core::cast::transmute;
 use core::cmp::{Eq, Ord};
 use core::ptr::to_unsafe_ptr;
@@ -21,90 +30,122 @@ use vec::Vec3;
  * # Type parameters
  *
  * * `T` - The type of the components. Should be a floating point type.
- * * `V3` - The 3-dimensional vector containing the three imaginary components
+ * * `V3` - The 3-dimensional vector type that will containin the imaginary
- *          of the quaternion.
+ *          components of the quaternion.
  */
 pub trait Quaternion<T,V3>: Dimensional<T>, ToPtr<T>, Eq, Neg<self> {
     /**
-     * Returns the multiplicative identity, ie: `q = 1 + 0i + 0j + 0i`
+     * # Return value
+     *
+     * The multiplicative identity, ie: `q = 1 + 0i + 0j + 0i`
      */
     static pure fn identity() -> self;
     
     /**
-     * Returns the additive identity, ie: `q = 0 + 0i + 0j + 0i`
+     * # Return value
+     *
+     * The additive identity, ie: `q = 0 + 0i + 0j + 0i`
      */
     static pure fn zero() -> self;
     
     /**
-     * Returns the result of multiplying the quaternion a scalar
+     * # Return value
+     *
+     * 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
+     * # Return value
+     *
+     * 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
+     * # Return value
+     *
+     * The result of multiplying the quaternion by a vector
      */
     pure fn mul_v(&self, vec: &V3) -> V3;
     
     /**
-     * Returns the sum of this quaternion and `other` 
+     * # Return value
+     *
+     * The sum of this quaternion and `other` 
      */
     pure fn add_q(&self, other: &self) -> self;
     
     /**
-     * Returns the sum of this quaternion and `other` 
+     * # Return value
+     *
+     * 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`
+     * # Return value
+     *
+     * The the result of multipliplying the quaternion by `other`
      */
     pure fn mul_q(&self, other: &self) -> self;
     
     /**
+     * # Return value
+     *
      * The dot product of the quaternion and `other`
      */
     pure fn dot(&self, other: &self) -> T;
     
     /**
-     * Returns the conjugate of the quaternion
+     * # Return value
+     *
+     * The conjugate of the quaternion
      */
     pure fn conjugate(&self) -> self;
     
     /**
-     * Returns the multiplicative inverse of the quaternion
+     * # Return value
+     *
+     * The multiplicative inverse of the quaternion
      */
     pure fn inverse(&self) -> self;
     
     /**
-     * Returns the squared magnitude of the quaternion. This is useful for
+     * # Return value
+     *
+     * The squared magnitude of the quaternion. This is useful for
      * magnitude comparisons where the exact magnitude does not need to be
      * calculated.
      */
     pure fn magnitude2(&self) -> T;
     
     /**
-     * Returns the magnitude of the quaternion
+     * # Return value
+     *
+     * The magnitude of the quaternion
      *
      * # Performance notes
      *
-     * For instances where the exact magnitude of the vector does not need to be
+     * For instances where the exact magnitude of the quaternion does not need
-     * known, for example for quaternion-quaternion magnitude comparisons,
+     * to be known, for example for quaternion-quaternion magnitude comparisons,
      * it is advisable to use the `magnitude2` method instead.
      */
     pure fn magnitude(&self) -> T;
     
     /**
-     * Returns the normalized quaternion
+     * # Return value
+     *
+     * The normalized quaternion
      */
     pure fn normalize(&self) -> self;
     
     /**
      * Normalised linear interpolation
+     *
+     * # Return value
+     *
+     * The intoperlated quaternion
      */
     pure fn nlerp(&self, other: &self, amount: T) -> self;
     
@@ -112,6 +153,10 @@ pub trait Quaternion<T,V3>: Dimensional<T>, ToPtr<T>, Eq, Neg<self> {
      * Perform a spherical linear interpolation between the quaternion and
      * `other`.
      *
+     * # Return value
+     *
+     * The intoperlated quaternion
+     *
      * # Performance notes
      *
      * This is more accurate than `nlerp` but is also more

src/vec.rs

@@ -66,7 +66,7 @@ pub trait NumericVector<T>: Vector<T>, Neg<self> {
     /**
      * The standard basis vector
      *
-     * # Returns
+     * # Return value
      *
      * A vector with each component set to one
      */
@@ -75,34 +75,44 @@ pub trait NumericVector<T>: Vector<T>, Neg<self> {
     /**
      * The null vector
      *
-     * # Returns
+     * # Return value
      *
      * A vector with each component set to zero
      */
     static pure fn zero() -> self;
     
     /**
-     * Returns the scalar multiplication of the vector and `value`
+     * # Return value
+     *
+     * The scalar multiplication of the vector and `value`
      */
     pure fn mul_t(&self, value: T) -> self;
     
     /**
-     * Returns the scalar division of the vector and `value`
+     * # Return value
+     *
+     * The scalar division of the vector and `value`
      */
     pure fn div_t(&self, value: T) -> self;
     
     /**
-     * Returns the sum of the vector and `other`
+     * # Return value
+     *
+     * The sum of the vector and `other`
      */
     pure fn add_v(&self, other: &self) -> self;
     
     /**
-     * Returns the difference between the vector and `other`
+     * # Return value
+     *
+     * The difference between the vector and `other`
      */
     pure fn sub_v(&self, other: &self) -> self;
     
     /**
-     * Returns the dot product of the vector and `other`
+     * # Return value
+     *
+     * The dot product of the vector and `other`
      */
     pure fn dot(&self, other: &self) -> T;
 }
@@ -154,7 +164,9 @@ pub trait NumericVector3<T>: NumericVector<T> {
     // static pure fn unit_z() -> self;
     
     /**
-     * Returns the cross product of the vector and `other`
+     * # Return value
+     *
+     * The cross product of the vector and `other`
      */
     pure fn cross(&self, other: &self) -> self;
 }
@@ -188,32 +200,53 @@ pub trait NumericVector4<T>: NumericVector<T> {
  */
 pub trait EuclideanVector<T>: NumericVector<T> {
     /**
-     * Returns the squared length of the vector
+     * # Return value
+     *
+     * The squared length of the vector. This is useful for comparisons where
+     * the exact length does not need to be calculated.
      */
     pure fn length2(&self) -> T;
     
     /**
-     * Returns the length of the vector
+     * # Return value
+     *
+     * The length of the vector
+     *
+     * # Performance notes
+     *
+     * For instances where the exact length of the vector does not need to be
+     * known, for example for quaternion-quaternion length comparisons,
+     * it is advisable to use the `length2` method instead.
      */
     pure fn length(&self) -> T;
     
     /**
-     * Returns the squared distance between the vector and `other`.
+     * # Return value
+     *
+     * The squared distance between the vector and `other`.
      */
     pure fn distance2(&self, other: &self) -> T;
     
     /**
-     * Returns the distance between the vector and `other`
+     * # Return value
+     *
+     * The distance between the vector and `other`
      */
     pure fn distance(&self, other: &self) -> T;
     
     /**
-     * Returns the normalized vector
+     * # Return value
+     *
+     * The normalized vector
      */
     pure fn normalize(&self) -> self;
     
     /**
      * Linearly intoperlate between the vector and `other`
+     *
+     * # Return value
+     *
+     * The intoperlated vector
      */
     pure fn lerp(&self, other: &self, amount: T) -> self;
 }
@@ -243,7 +276,17 @@ pub trait MutableEuclideanVector<T>: MutableNumericVector<&self/T>,
 
 
 /**
- *  Vec2
+ * A 2-dimensional vector
+ *
+ * # Type parameters
+ *
+ * * `T` - The type of the components. This is intended to support boolean,
+ *         integer, unsigned integer, and floating point types.
+ *
+ * # Fields
+ *
+ * * `x` - the first component of the vector
+ * * `y` - the second component of the vector
  */
 pub struct Vec2<T> { x: T, y: T }
 
@@ -468,7 +511,18 @@ pub impl<T:Copy DefaultEq> Vec2<T>: DefaultEq {
 
 
 /**
- *  Vec3
+ * A 3-dimensional vector
+ *
+ * # Type parameters
+ *
+ * * `T` - The type of the components. This is intended to support boolean,
+ *         integer, unsigned integer, and floating point types.
+ *
+ * # Fields
+ *
+ * * `x` - the first component of the vector
+ * * `y` - the second component of the vector
+ * * `z` - the third component of the vector
  */
 pub struct Vec3<T> { x: T, y: T, z: T }
 
@@ -724,7 +778,19 @@ pub impl<T:Copy DefaultEq> Vec3<T>: DefaultEq {
 
 
 /**
- *  Vec4
+ * A 4-dimensional vector
+ *
+ * # Type parameters
+ *
+ * * `T` - The type of the components. This is intended to support boolean,
+ *         integer, unsigned integer, and floating point types.
+ *
+ * # Fields
+ *
+ * * `x` - the first component of the vector
+ * * `y` - the second component of the vector
+ * * `z` - the third component of the vector
+ * * `w` - the fourth component of the vector
  */
 pub struct Vec4<T> { x: T, y: T, z: T, w: T }