Add documentation.

src/adaptors/rotmat.rs

@@ -16,18 +16,23 @@ use vec::Vec1;
 use mat::{Mat2, Mat3};
 use vec::Vec3;
 
+/// Matrix wrapper representing rotation matrix. It is built uppon another matrix and ensures (at
+/// the type-level) that it will always represent a rotation. Rotation matrices have some
+/// properties useful for performances, like the fact that the inversion is simply a transposition.
 #[deriving(Eq, ToStr, Clone)]
 pub struct Rotmat<M>
 { priv submat: M }
 
 impl<M: Clone> Rotmat<M>
 {
+  /// Gets a copy of the internal representation of the rotation.
   pub fn submat(&self) -> M
   { self.submat.clone() }
 }
 
 impl<N: Clone + Trigonometric + Neg<N>> Rotmat<Mat2<N>>
 {
+  /// Builds a 2 dimensional rotation matrix from an angle in radian.
   pub fn from_angle(angle: N) -> Rotmat<Mat2<N>>
   {
     let (sia, coa) = angle.sin_cos();
@@ -38,6 +43,11 @@ impl<N: Clone + Trigonometric + Neg<N>> Rotmat<Mat2<N>>
 
 impl<N: Clone + Trigonometric + DivisionRing + Algebraic> Rotmat<Mat3<N>>
 {
+  /// Builds a 3 dimensional rotation matrix from an axis and an angle.
+  ///
+  /// # Arguments
+  ///   * `axisangle` - A vector representing the rotation. Its magnitude is the amount of rotation
+  ///   in radian. Its direction is the axis of rotation.
   pub fn from_axis_angle(axisangle: Vec3<N>) -> Rotmat<Mat3<N>>
   {
     if axisangle.sqnorm().is_zero()
@@ -76,6 +86,15 @@ impl<N: Clone + Trigonometric + DivisionRing + Algebraic> Rotmat<Mat3<N>>
 
 impl<N: Clone + DivisionRing + Algebraic> Rotmat<Mat3<N>>
 {
+  /// Reorient this matrix such that its local `x` axis points to a given point. Note that the
+  /// usually known `look_at` function does the same thing but with the `z` axis. See `look_at_z`
+  /// for that.
+  ///
+  /// # Arguments
+  ///   * at - The point to look at. It is also the direction the matrix `x` axis will be aligned
+  ///   with
+  ///   * up - Vector pointing `up`. The only requirement of this parameter is to not be colinear
+  ///   with `at`. Non-colinearity is not checked.
   pub fn look_at(&mut self, at: &Vec3<N>, up: &Vec3<N>)
   {
     let xaxis = at.normalized();
@@ -87,6 +106,13 @@ impl<N: Clone + DivisionRing + Algebraic> Rotmat<Mat3<N>>
                             xaxis.z        , yaxis.z        , zaxis.z)
   }
 
+  /// Reorient this matrix such that its local `z` axis points to a given point. 
+  ///
+  /// # Arguments
+  ///   * at - The point to look at. It is also the direction the matrix `y` axis will be aligned
+  ///   with
+  ///   * up - Vector pointing `up`. The only requirement of this parameter is to not be colinear
+  ///   with `at`. Non-colinearity is not checked.
   pub fn look_at_z(&mut self, at: &Vec3<N>, up: &Vec3<N>)
   {
     let zaxis = at.normalized();

src/adaptors/transform.rs

@@ -15,6 +15,13 @@ use adaptors::rotmat::Rotmat;
 use vec::Vec3;
 use mat::Mat3;
 
+/// Matrix-Vector wrapper used to represent a matrix multiplication followed by a translation.
+/// Usually, a matrix in homogeneous coordinate is used to be able to apply an affine transform with
+/// a translation to a vector. This is weird because it makes a `n`-dimentional transformation be
+/// an `n + 1`-matrix. Using the `Transform` wrapper avoid homogeneous coordinates by having the
+/// translation separate from the other transformations. This is particularity useful when the
+/// underlying transform is a rotation (see `Rotmat`): this makes inversion much faster than
+/// inverting the homogeneous matrix itself.
 #[deriving(Eq, ToStr, Clone)]
 pub struct Transform<M, V>
 {
@@ -24,6 +31,7 @@ pub struct Transform<M, V>
 
 impl<M, V> Transform<M, V>
 {
+  /// Builds a new transform from a matrix and a vector.
   #[inline]
   pub fn new(mat: M, trans: V) -> Transform<M, V>
   { Transform { submat: mat, subtrans: trans } }
@@ -31,10 +39,12 @@ impl<M, V> Transform<M, V>
 
 impl<M: Clone, V: Clone> Transform<M, V>
 {
+  /// Gets a copy of the internal matrix.
   #[inline]
   pub fn submat(&self) -> M
   { self.submat.clone() }
 
+  /// Gets a copy of the internal translation.
   #[inline]
   pub fn subtrans(&self) -> V
   { self.subtrans.clone() }
@@ -42,12 +52,31 @@ impl<M: Clone, V: Clone> Transform<M, V>
 
 impl<N: Clone + DivisionRing + Algebraic> Transform<Rotmat<Mat3<N>>, Vec3<N>>
 {
+  /// Reorient and translate this transformation such that its local `x` axis points to a given
+  /// direction.  Note that the usually known `look_at` function does the same thing but with the
+  /// `z` axis. See `look_at_z` for that.
+  ///
+  /// # Arguments
+  ///   * eye - The new translation of the transformation.
+  ///   * at - The point to look at. `at - eye` is the direction the matrix `x` axis will be
+  ///   aligned with
+  ///   * up - Vector pointing `up`. The only requirement of this parameter is to not be colinear
+  ///   with `at`. Non-colinearity is not checked.
   pub fn look_at(&mut self, eye: &Vec3<N>, at: &Vec3<N>, up: &Vec3<N>)
   {
     self.submat.look_at(&(*at - *eye), up);
     self.subtrans = eye.clone();
   }
 
+  /// Reorient and translate this transformation such that its local `z` axis points to a given
+  /// direction. 
+  ///
+  /// # Arguments
+  ///   * eye - The new translation of the transformation.
+  ///   * at - The point to look at. `at - eye` is the direction the matrix `x` axis will be
+  ///   aligned with
+  ///   * up - Vector pointing `up`. The only requirement of this parameter is to not be colinear
+  ///   with `at`. Non-colinearity is not checked.
   pub fn look_at_z(&mut self, eye: &Vec3<N>, at: &Vec3<N>, up: &Vec3<N>)
   {
     self.submat.look_at_z(&(*at - *eye), up);
@@ -281,8 +310,7 @@ FromHomogeneous<M> for Transform<M2, V>
 {
   fn from(m: &M) -> Transform<M2, V>
   {
-    Transform::new(FromHomogeneous::from(m),
+    Transform::new(FromHomogeneous::from(m), m.column(Dim::dim::<M>() - 1))
-                   m.column(Dim::dim::<M>() - 1))
   }
 }
 

src/dmat.rs

@@ -9,21 +9,33 @@ use traits::transpose::Transpose;
 use traits::rlmul::{RMul, LMul};
 use dvec::{DVec, zero_vec_with_dim};
 
+/// Square matrix with a dimension unknown at compile-time.
 #[deriving(Eq, ToStr, Clone)]
 pub struct DMat<N>
 {
-  dim: uint, // FIXME: handle more than just square matrices
+  priv dim: uint, // FIXME: handle more than just square matrices
-  mij: ~[N]
+  priv mij: ~[N]
 }
 
+/// Builds a matrix filled with zeros.
+/// 
+/// # Arguments
+///   * `dim` - The dimension of the matrix. A `dim`-dimensional matrix contains `dim * dim`
+///   components.
 #[inline]
 pub fn zero_mat_with_dim<N: Zero + Clone>(dim: uint) -> DMat<N>
 { DMat { dim: dim, mij: from_elem(dim * dim, Zero::zero()) } }
 
+/// Tests if all components of the matrix are zeroes.
 #[inline]
 pub fn is_zero_mat<N: Zero>(mat: &DMat<N>) -> bool
 { mat.mij.iter().all(|e| e.is_zero()) }
 
+/// Builds an identity matrix.
+/// 
+/// # Arguments
+///   * `dim` - The dimension of the matrix. A `dim`-dimensional matrix contains `dim * dim`
+///   components.
 #[inline]
 pub fn one_mat_with_dim<N: Clone + One + Zero>(dim: uint) -> DMat<N>
 {
@@ -39,9 +51,14 @@ pub fn one_mat_with_dim<N: Clone + One + Zero>(dim: uint) -> DMat<N>
 impl<N: Clone> DMat<N>
 {
   #[inline]
-  pub fn offset(&self, i: uint, j: uint) -> uint
+  fn offset(&self, i: uint, j: uint) -> uint
   { i * self.dim + j }
 
+  /// Changes the value of a component of the matrix.
+  ///
+  /// # Arguments
+  ///   * `i` - 0-based index of the line to be changed
+  ///   * `j` - 0-based index of the column to be changed
   #[inline]
   pub fn set(&mut self, i: uint, j: uint, t: &N)
   {
@@ -50,6 +67,11 @@ impl<N: Clone> DMat<N>
     self.mij[self.offset(i, j)] = t.clone()
   }
 
+  /// Reads the value of a component of the matrix.
+  ///
+  /// # Arguments
+  ///   * `i` - 0-based index of the line to be read
+  ///   * `j` - 0-based index of the column to be read
   #[inline]
   pub fn at(&self, i: uint, j: uint) -> N
   {

src/dvec.rs

@@ -13,16 +13,23 @@ use traits::norm::Norm;
 use traits::translation::{Translation, Translatable};
 use traits::scalar_op::{ScalarMul, ScalarDiv, ScalarAdd, ScalarSub};
 
+/// Vector with a dimension unknown at compile-time.
 #[deriving(Eq, Ord, ToStr, Clone)]
 pub struct DVec<N>
 {
+  /// Components of the vector. Contains as much elements as the vector dimension.
   at: ~[N]
 }
 
+/// Builds a vector filled with zeros.
+/// 
+/// # Arguments
+///   * `dim` - The dimension of the vector.
 #[inline]
 pub fn zero_vec_with_dim<N: Zero + Clone>(dim: uint) -> DVec<N>
 { DVec { at: from_elem(dim, Zero::zero::<N>()) } }
 
+/// Tests if all components of the vector are zeroes.
 #[inline]
 pub fn is_zero_vec<N: Zero>(vec: &DVec<N>) -> bool
 { vec.at.iter().all(|e| e.is_zero()) }
@@ -52,9 +59,11 @@ impl<N, Iter: Iterator<N>> FromIterator<N, Iter> for DVec<N>
   }
 }
 
-// FIXME: is Clone needed?
 impl<N: Clone + DivisionRing + Algebraic + ApproxEq<N>> DVec<N>
 {
+  /// Computes the canonical basis for the given dimension. A canonical basis is a set of
+  /// vectors, mutually orthogonal, with all its component equal to 0.0 exept one which is equal to
+  /// 1.0.
   pub fn canonical_basis_with_dim(dim: uint) -> ~[DVec<N>]
   {
     let mut res : ~[DVec<N>] = ~[];
@@ -71,6 +80,8 @@ impl<N: Clone + DivisionRing + Algebraic + ApproxEq<N>> DVec<N>
     res
   }
 
+  /// Computes a basis of the space orthogonal to the vector. If the input vector is of dimension
+  /// `n`, this will return `n - 1` vectors.
   pub fn orthogonal_subspace_basis(&self) -> ~[DVec<N>]
   {
     // compute the basis of the orthogonal subspace using Gram-Schmidt

src/mat.rs

@@ -1,3 +1,5 @@
+#[allow(missing_doc)]; // we allow missing to avoid having to document the mij components.
+
 use std::cast;
 use std::uint::iterate;
 use std::num::{One, Zero};
@@ -28,9 +30,12 @@ pub use traits::transpose::*;
 
 mod mat_macros;
 
+/// Square matrix of dimension 1.
 #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)]
 pub struct Mat1<N>
-{ m11: N }
+{
+  m11: N
+}
 
 mat_impl!(Mat1, m11)
 mat_cast_impl!(Mat1, m11)
@@ -50,6 +55,7 @@ column_impl!(Mat1, 1)
 to_homogeneous_impl!(Mat1, Mat2, 1, 2)
 from_homogeneous_impl!(Mat1, Mat2, 1, 2)
 
+/// Square matrix of dimension 2.
 #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)]
 pub struct Mat2<N>
 {
@@ -78,6 +84,7 @@ column_impl!(Mat2, 2)
 to_homogeneous_impl!(Mat2, Mat3, 2, 3)
 from_homogeneous_impl!(Mat2, Mat3, 2, 3)
 
+/// Square matrix of dimension 3.
 #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)]
 pub struct Mat3<N>
 {
@@ -110,6 +117,7 @@ column_impl!(Mat3, 3)
 to_homogeneous_impl!(Mat3, Mat4, 3, 4)
 from_homogeneous_impl!(Mat3, Mat4, 3, 4)
 
+/// Square matrix of dimension 4.
 #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)]
 pub struct Mat4<N>
 {
@@ -150,6 +158,7 @@ column_impl!(Mat4, 4)
 to_homogeneous_impl!(Mat4, Mat5, 4, 5)
 from_homogeneous_impl!(Mat4, Mat5, 4, 5)
 
+/// Square matrix of dimension 5.
 #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)]
 pub struct Mat5<N>
 {
@@ -196,6 +205,7 @@ column_impl!(Mat5, 5)
 to_homogeneous_impl!(Mat5, Mat6, 5, 6)
 from_homogeneous_impl!(Mat5, Mat6, 5, 6)
 
+/// Square matrix of dimension 6.
 #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)]
 pub struct Mat6<N>
 {

src/nalgebra.rc

@@ -8,7 +8,11 @@
        , author = "Sébastien Crozet"
        , uuid = "1E96070F-4778-4EC1-B080-BF69F7048216")];
 #[crate_type = "lib"];
-#[warn(non_camel_case_types)]
+#[deny(non_camel_case_types)];
+#[deny(non_uppercase_statics)];
+#[deny(unnecessary_qualification)];
+#[deny(missing_doc)];
+#[deny(warnings)];
 
 extern mod std;
 extern mod extra;

src/traits/basis.rs

@@ -1,7 +1,31 @@
+/// Traits of objecs which can form a basis.
 pub trait Basis
 {
-  /// Computes the canonical basis of the space in which this object lives.
+  /// Iterate through the canonical basis of the space in which this object lives.
-  // FIXME: implement the for loop protocol?
   fn canonical_basis(&fn(Self));
+
+  /// Iterate through a basis of the subspace orthogonal to `self`.
   fn orthonormal_subspace_basis(&self, &fn(Self));
+
+  /// Creates the canonical basis of the space in which this object lives.
+  fn canonical_basis_list() -> ~[Self]
+  {
+    let mut res = ~[];
+
+    do Basis::canonical_basis::<Self> |elem|
+    { res.push(elem) }
+
+    res
+  }
+
+  /// Creates a basis of the subspace orthogonal to `self`.
+  fn orthonormal_subspace_basis_list(&self) -> ~[Self]
+  {
+    let mut res = ~[];
+
+    do self.orthonormal_subspace_basis |elem|
+    { res.push(elem) }
+
+    res
+  }
 }

src/traits/column.rs

@@ -1,5 +1,8 @@
+/// Traits to access columns of a matrix.
 pub trait Column<C>
 {
-  fn set_column(&mut self, uint, C);
+  /// Reads the `i`-th column of `self`.
-  fn column(&self, uint) -> C;
+  fn column(&self, i: uint) -> C;
+  /// Writes the `i`-th column of `self`.
+  fn set_column(&mut self, i: uint, C);
 }

src/traits/dim.rs

@@ -12,63 +12,55 @@ pub trait Dim {
 /// Dimensional token for 0-dimensions. Dimensional tokens are the preferred
 /// way to specify at the type level the dimension of n-dimensional objects.
 #[deriving(Eq, Ord, ToStr)]
-pub struct d0;
+pub struct D0;
 
 /// Dimensional token for 1-dimension. Dimensional tokens are the preferred
 /// way to specify at the type level the dimension of n-dimensional objects.
 #[deriving(Eq, Ord, ToStr)]
-pub struct d1;
+pub struct D1;
 
 /// Dimensional token for 2-dimensions. Dimensional tokens are the preferred
 /// way to specify at the type level the dimension of n-dimensional objects.
 #[deriving(Eq, Ord, ToStr)]
-pub struct d2;
+pub struct D2;
 
 /// Dimensional token for 3-dimensions. Dimensional tokens are the preferred
 /// way to specify at the type level the dimension of n-dimensional objects.
 #[deriving(Eq, Ord, ToStr)]
-pub struct d3;
+pub struct D3;
 
 /// Dimensional token for 4-dimensions. Dimensional tokens are the preferred
 /// way to specify at the type level the dimension of n-dimensional objects.
 #[deriving(Eq, Ord, ToStr)]
-pub struct d4;
+pub struct D4;
 
 /// Dimensional token for 5-dimensions. Dimensional tokens are the preferred
 /// way to specify at the type level the dimension of n-dimensional objects.
 #[deriving(Eq, Ord, ToStr)]
-pub struct d5;
+pub struct D5;
 
 /// Dimensional token for 6-dimensions. Dimensional tokens are the preferred
 /// way to specify at the type level the dimension of n-dimensional objects.
 #[deriving(Eq, Ord, ToStr)]
-pub struct d6;
+pub struct D6;
 
-/// Dimensional token for 7-dimensions. Dimensional tokens are the preferred
+impl Dim for D0
-/// way to specify at the type level the dimension of n-dimensional objects.
-#[deriving(Eq, Ord, ToStr)]
-pub struct d7;
-
-impl Dim for d0
 { fn dim() -> uint { 0 } }
 
-impl Dim for d1
+impl Dim for D1
 { fn dim() -> uint { 1 } }
 
-impl Dim for d2
+impl Dim for D2
 { fn dim() -> uint { 2 } }
 
-impl Dim for d3
+impl Dim for D3
 { fn dim() -> uint { 3 } }
 
-impl Dim for d4
+impl Dim for D4
 { fn dim() -> uint { 4 } }
 
-impl Dim for d5
+impl Dim for D5
 { fn dim() -> uint { 5 } }
 
-impl Dim for d6
+impl Dim for D6
 { fn dim() -> uint { 6 } }
-
-impl Dim for d7
-{ fn dim() -> uint { 7 } }

src/traits/homogeneous.rs

@@ -1,9 +1,15 @@
+/// Traits of objects which can be put in homogeneous coordinates.
 pub trait ToHomogeneous<U>
 {
+  /// Gets the homogeneous coordinates version of this object.
   fn to_homogeneous(&self) -> U;
 }
 
+/// Traits of objects which can be build from an homogeneous coordinate representation.
 pub trait FromHomogeneous<U>
 {
+  /// Builds an object with its homogeneous coordinate version. Note this it is not required for
+  /// `from` to be the iverse of `to_homogeneous`. Typically, `from` will remove some informations
+  /// unrecoverable by `to_homogeneous`.
   fn from(&U) -> Self;
 }

src/traits/indexable.rs

@@ -2,9 +2,17 @@
 // however, it is needed because std::ops::Index is (strangely) to poor: it
 // does not have a function to set values.
 // Also, using Index with tuples crashes.
+/// This is a workaround trait.
+///
+/// It exists because the `Index` trait cannot be used to express write access.
+/// Thus, this is the same as the `Index` trait but without the syntactic sugar and with a method
+/// to write to a specific index.
 pub trait Indexable<Index, Res>
 {
-  fn at(&self, Index) -> Res;
+  /// Reads the `i`-th element of `self`.
-  fn set(&mut self, Index, Res);
+  fn at(&self, i: Index) -> Res;
-  fn swap(&mut self, Index, Index);
+  /// Writes to the `i`-th element of `self`.
+  fn set(&mut self, i: Index, Res);
+  /// Swaps the `i`-th element of `self` with its `j`-th element.
+  fn swap(&mut self, i: Index, j: Index);
 }

src/traits/iterable.rs

@@ -1,12 +1,16 @@
 use std::vec;
 
+/// Traits of objects which can be iterated through like a vector.
 pub trait Iterable<N>
 {
+  /// Gets a vector-like read-only iterator.
   fn iter<'l>(&'l self) -> vec::VecIterator<'l, N>;
 }
 
+/// Traits of mutable objects which can be iterated through like a vector.
 pub trait IterableMut<N>
 {
+  /// Gets a vector-like read-write iterator.
   fn mut_iter<'l>(&'l mut self) -> vec::VecMutIterator<'l, N>;
 }
 

src/traits/mat_cast.rs

@@ -1,2 +1,7 @@
+/// Trait of matrices which can be converted to another matrix. Used to change the type of a matrix
+/// components.
 pub trait MatCast<M>
-{ fn from(Self) -> M; }
+{
+  /// Converts `m` to have the type `M`.
+  fn from(m: Self) -> M;
+}

src/traits/rotation.rs

@@ -8,12 +8,16 @@ pub trait Rotation<V>
   /// Gets the rotation associated with this object.
   fn rotation(&self) -> V;
 
+  /// Gets the inverse rotation associated with this object.
   fn inv_rotation(&self) -> V;
 
-  /// In-place version of `rotated`.
+  /// In-place version of `rotated` (see the `Rotatable` trait).
   fn rotate_by(&mut self, &V);
 }
 
+/// Trait of objects which can be put on an alternate form which represent a rotation. This is
+/// typically implemented by structures requiring an internal restructuration to be able to
+/// represent a rotation.
 pub trait Rotatable<V, Res: Rotation<V>>
 {
   /// Appends a rotation from an alternative representation. Such
@@ -21,9 +25,13 @@ pub trait Rotatable<V, Res: Rotation<V>>
   fn rotated(&self, &V) -> Res;
 }
 
+/// Trait of objects able to rotate other objects. This is typically implemented by matrices which
+/// rotate vectors.
 pub trait Rotate<V>
 {
+  /// Apply a rotation to an object.
   fn rotate(&self, &V)     -> V;
+  /// Apply an inverse rotation to an object.
   fn inv_rotate(&self, &V) -> V;
 }
 
@@ -49,6 +57,12 @@ pub fn rotated_wrt_point<M: Translatable<LV, M2>,
   res
 }
 
+/// Rotates an object using a specific center of rotation.
+///
+/// # Arguments
+///   * `m` - the object to be rotated
+///   * `ammount` - the rotation to be applied
+///   * `center` - the new center of rotation
 #[inline]
 pub fn rotate_wrt_point<M:  Rotation<AV> + Translation<LV>,
                         LV: Neg<LV>,
@@ -63,8 +77,9 @@ pub fn rotate_wrt_point<M:  Rotation<AV> + Translation<LV>,
 /**
  * Applies a rotation centered on the input translation.
  *
- *   - `m`:       the object to be rotated.
+ * # Arguments
- *   - `ammount`: the rotation to apply.
+ *   * `m` - the object to be rotated.
+ *   * `ammount` - the rotation to apply.
  */
 #[inline]
 pub fn rotated_wrt_center<M: Translatable<LV, M2> + Translation<LV>,
@@ -77,8 +92,9 @@ pub fn rotated_wrt_center<M: Translatable<LV, M2> + Translation<LV>,
 /**
  * Applies a rotation centered on the input translation.
  *
- *   - `m`:       the object to be rotated.
+ * # Arguments
- *   - `ammount`: the rotation to apply.
+ *   * `m` - the object to be rotated.
+ *   * `ammount` - the rotation to apply.
  */
 #[inline]
 pub fn rotate_wrt_center<M: Translatable<LV, M> + Translation<LV> + Rotation<AV>,

src/traits/sample.rs

@@ -1,4 +1,18 @@
+/// Traits of vectors able to sample a sphere. The number of sample must be sufficient to
+/// approximate a sphere using support mapping functions.
 pub trait UniformSphereSample
 {
+  /// Iterate throught the samples.
   pub fn sample(&fn(&'static Self));
+
+  /// Gets the list of all samples.
+  pub fn sample_list() -> ~[&'static Self]
+  {
+    let mut res = ~[];
+
+    do UniformSphereSample::sample::<Self> |s|
+    { res.push(s) }
+
+    res
+  }
 }

src/traits/sub_dot.rs

@@ -1,9 +1,10 @@
 use traits::dot::Dot;
 
+/// Traits of objects with a subtract and a dot product. Exists only for optimization purpose.
 pub trait SubDot<N> : Sub<Self, Self> + Dot<N>
 {
   /**
-   * Short-cut to compute the projecton of a point on a vector, but without
+   * Short-cut to compute the projection of a point on a vector, but without
    * computing intermediate vectors.
    * This must be equivalent to:
    *

src/traits/transformation.rs

@@ -1,21 +1,36 @@
+/// Trait of object which represent a transformation, and to wich new transformations can
+/// be appended. A transformation is assumed to be an isomitry without translation
+/// and without reflexion.
 pub trait Transformation<M>
 {
+  /// Gets the transformation associated with this object.
   fn transformation(&self) -> M;
 
+  /// Gets the inverse transformation associated with this object.
   fn inv_transformation(&self) -> M;
 
+  /// In-place version of `transformed` (see the `Transformable` trait).
   fn transform_by(&mut self, &M);
 }
 
+/// Trait of objects able to transform other objects. This is typically implemented by matrices which
+/// transform vectors.
 pub trait Transform<V>
 {
   // XXX: sadly we cannot call this `transform` as it conflicts with the
   // iterators' `transform` function (which seems always exist).
+  /// Apply a transformation to an object.
   fn transform_vec(&self, &V) -> V;
+  /// Apply an inverse transformation to an object.
   fn inv_transform(&self, &V) -> V;
 }
 
+/// Trait of objects which can be put on an alternate form which represent a transformation. This is
+/// typically implemented by structures requiring an internal restructuration to be able to
+/// represent a transformation.
 pub trait Transformable<M, Res: Transformation<M>>
 {
+  /// Appends a transformation from an alternative representation. Such
+  /// representation has the same format as the one returned by `transformation`.
   fn transformed(&self, &M) -> Res;
 }

src/traits/translation.rs

@@ -6,18 +6,26 @@ pub trait Translation<V>
   /// Gets the translation associated with this object.
   fn translation(&self) -> V;
 
+  /// Gets the inverse translation associated with this object.
   fn inv_translation(&self) -> V;
 
-  /// In-place version of `translate`.
+  /// In-place version of `translated` (see the `Translatable` trait).
   fn translate_by(&mut self, &V);
 }
 
+/// Trait of objects able to rotate other objects. This is typically implemented by matrices which
+/// rotate vectors.
 pub trait Translate<V>
 {
+  /// Apply a translation to an object.
   fn translate(&self, &V)     -> V;
+  /// Apply an inverse translation to an object.
   fn inv_translate(&self, &V) -> V;
 }
 
+/// Trait of objects which can be put on an alternate form which represent a translation. This is
+/// typically implemented by structures requiring an internal restructuration to be able to
+/// represent a translation.
 pub trait Translatable<V, Res: Translation<V>>
 {
   /// Appends a translation from an alternative representation. Such

src/traits/vec_cast.rs

@@ -1,2 +1,7 @@
+/// Trait of vectors which can be converted to another matrix. Used to change the type of a vector
+/// components.
 pub trait VecCast<V>
-{ fn from(Self) -> V; }
+{
+  /// Converts `v` to have the type `V`.
+  fn from(v: Self) -> V;
+}

src/vec.rs

@@ -27,12 +27,17 @@ pub use traits::scalar_op::*;
 
 mod vec_macros;
 
+/// Vector of dimension 0.
 #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, Rand, Zero, ToStr)]
 pub struct Vec0<N>;
 
+/// Vector of dimension 1.
 #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)]
 pub struct Vec1<N>
-{ x: N }
+{
+  /// First component of the vector.
+  x: N
+}
 
 new_impl!(Vec1, x)
 vec_cast_impl!(Vec1, x)
@@ -61,10 +66,13 @@ iterable_mut_impl!(Vec1, 1)
 to_homogeneous_impl!(Vec1, Vec2, y, x)
 from_homogeneous_impl!(Vec1, Vec2, y, x)
 
+/// Vector of dimension 2.
 #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)]
 pub struct Vec2<N>
 {
+  /// First component of the vector.
   x: N,
+  /// Second component of the vector.
   y: N
 }
 
@@ -95,14 +103,20 @@ iterable_mut_impl!(Vec2, 2)
 to_homogeneous_impl!(Vec2, Vec3, z, x, y)
 from_homogeneous_impl!(Vec2, Vec3, z, x, y)
 
+/// Vector of dimension 3.
 #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)]
 pub struct Vec3<N>
+
 {
+  /// First component of the vector.
   x: N,
+  /// Second component of the vector.
   y: N,
+  /// Third component of the vector.
   z: N
 }
 
+
 new_impl!(Vec3, x, y, z)
 vec_cast_impl!(Vec3, x, y, z)
 indexable_impl!(Vec3, 3)
@@ -130,12 +144,17 @@ iterable_mut_impl!(Vec3, 3)
 to_homogeneous_impl!(Vec3, Vec4, w, x, y, z)
 from_homogeneous_impl!(Vec3, Vec4, w, x, y, z)
 
+/// Vector of dimension 4.
 #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)]
 pub struct Vec4<N>
 {
+  /// First component of the vector.
   x: N,
+  /// Second component of the vector.
   y: N,
+  /// Third component of the vector.
   z: N,
+  /// Fourth component of the vector.
   w: N
 }
 
@@ -166,14 +185,20 @@ iterable_mut_impl!(Vec4, 4)
 to_homogeneous_impl!(Vec4, Vec5, a, x, y, z, w)
 from_homogeneous_impl!(Vec4, Vec5, a, x, y, z, w)
 
+/// Vector of dimension 5.
 #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)]
 pub struct Vec5<N>
 {
+  /// First component of the vector.
   x: N,
+  /// Second component of the vector.
   y: N,
+  /// Third component of the vector.
   z: N,
+  /// Fourth component of the vector.
   w: N,
-  a: N,
+  /// Fifth of the vector.
+  a: N
 }
 
 new_impl!(Vec5, x, y, z, w, a)
@@ -203,14 +228,21 @@ iterable_mut_impl!(Vec5, 5)
 to_homogeneous_impl!(Vec5, Vec6, b, x, y, z, w, a)
 from_homogeneous_impl!(Vec5, Vec6, b, x, y, z, w, a)
 
+/// Vector of dimension 6.
 #[deriving(Eq, Ord, Encodable, Decodable, Clone, DeepClone, IterBytes, Rand, Zero, ToStr)]
 pub struct Vec6<N>
 {
+  /// First component of the vector.
   x: N,
+  /// Second component of the vector.
   y: N,
+  /// Third component of the vector.
   z: N,
+  /// Fourth component of the vector.
   w: N,
+  /// Fifth of the vector.
   a: N,
+  /// Sixth component of the vector.
   b: N
 }
 

src/vec0_spec.rs

@@ -19,6 +19,7 @@ use vec;
 
 impl<N> vec::Vec0<N>
 {
+  /// Creates a new vector.
   #[inline]
   pub fn new() -> vec::Vec0<N>
   { vec::Vec0 }
@@ -41,6 +42,7 @@ impl<N: Clone> Indexable<uint, N> for vec::Vec0<N>
 
 impl<N: Clone> vec::Vec0<N>
 {
+  /// Creates a new vector. The parameter is not taken in account.
   #[inline]
   pub fn new_repeat(_: N) -> vec::Vec0<N>
   { vec::Vec0 }

src/vec_macros.rs

@@ -4,6 +4,7 @@ macro_rules! new_impl(
   ($t: ident, $comp0: ident $(,$compN: ident)*) => (
     impl<N> $t<N>
     {
+      /// Creates a new vector.
       #[inline]
       pub fn new($comp0: N $( , $compN: N )*) -> $t<N>
       {
@@ -49,6 +50,7 @@ macro_rules! new_repeat_impl(
   ($t: ident, $param: ident, $comp0: ident $(,$compN: ident)*) => (
     impl<N: Clone> $t<N>
     {
+      /// Creates a new vector with all its components equal to a given value.
       #[inline]
       pub fn new_repeat($param: N) -> $t<N>
       {