Complete the documentation.

README.md

@@ -9,12 +9,12 @@ nalgebra
 * real time computer graphics.
 * real time computer physics.
 
-An on-line version of this documentation is available [here](http://nalgebra.org).
+An on-line version of this documentation is available [here](http://nalgebra.org/doc/nalgebra).
 
 ## Using **nalgebra**
-All the functionality of **nalgebra** is grouped in one place: the root module `nalgebra::`.
-This module re-exports everything and includes free functions for all traits methods doing
-out-of-place modifications.
+All the functionality of **nalgebra** is grouped in one place: the root module `nalgebra::`.  This
+module re-exports everything and includes free functions for all traits methods performing
+out-of-place operations.
 
 * You can import the whole prelude using:
 
@@ -46,12 +46,12 @@ an optimized set of tools for computer graphics and physics. Those features incl
 
 * Vectors with predefined static sizes: `Vec1`, `Vec2`, `Vec3`, `Vec4`, `Vec5`, `Vec6`.
 * Vector with a user-defined static size: `VecN`.
-* Points with static sizes: ``Pnt1`, `Pnt2`, `Pnt3`, `Pnt4`, `Pnt5`, `Pnt6`.
+* Points with static sizes: `Pnt1`, `Pnt2`, `Pnt3`, `Pnt4`, `Pnt5`, `Pnt6`.
 * Square matrices with static sizes: `Mat1`, `Mat2`, `Mat3`, `Mat4`, `Mat5`, `Mat6 `.
 * Rotation matrices: `Rot2`, `Rot3`
 * Quaternions: `Quat`, `UnitQuat`.
-* Isometries (translation * rotation): `Iso2`, `Iso3`
-* Similarity transformations (translation * rotation * uniform scale): `Sim2`, `Sim3`.
+* Isometries (translation ⨯ rotation): `Iso2`, `Iso3`
+* Similarity transformations (translation ⨯ rotation ⨯ uniform scale): `Sim2`, `Sim3`.
 * 3D projections for computer graphics: `Persp3`, `PerspMat3`, `Ortho3`, `OrthoMat3`.
 * Dynamically sized heap-allocated vector: `DVec`.
 * Dynamically sized stack-allocated vectors with a maximum size: `DVec1` to `DVec6`.

src/lib.rs

@@ -3,16 +3,16 @@
 
 **nalgebra** is a low-dimensional linear algebra library written for Rust targeting:
 
-* general-purpose linear algebra (still lacks a lot of features…).
+* low-dimensional general-purpose linear algebra (still lacks a lot of features…).
 * real time computer graphics.
 * real time computer physics.
 
-An on-line version of this documentation is available [here](http://nalgebra.org).
+An on-line version of this documentation is available [here](http://nalgebra.org/doc/nalgebra).
 
 ## Using **nalgebra**
-All the functionality of **nalgebra** is grouped in one place: the root module `nalgebra::`.
-This module re-exports everything and includes free functions for all traits methods doing
-out-of-place modifications.
+All the functionality of **nalgebra** is grouped in one place: the root module `nalgebra::`.  This
+module re-exports everything and includes free functions for all traits methods performing
+out-of-place operations.
 
 * You can import the whole prelude using:
 
@@ -47,8 +47,8 @@ an optimized set of tools for computer graphics and physics. Those features incl
 * Square matrices with static sizes: `Mat1`, `Mat2`, `Mat3`, `Mat4`, `Mat5`, `Mat6 `.
 * Rotation matrices: `Rot2`, `Rot3`
 * Quaternions: `Quat`, `UnitQuat`.
-* Isometries (translation * rotation): `Iso2`, `Iso3`
-* Similarity transformations (translation * rotation * uniform scale): `Sim2`, `Sim3`.
+* Isometries (translation ⨯ rotation): `Iso2`, `Iso3`
+* Similarity transformations (translation ⨯ rotation ⨯ uniform scale): `Sim2`, `Sim3`.
 * 3D projections for computer graphics: `Persp3`, `PerspMat3`, `Ortho3`, `OrthoMat3`.
 * Dynamically sized heap-allocated vector: `DVec`.
 * Dynamically sized stack-allocated vectors with a maximum size: `DVec1` to `DVec6`.

src/structs/dmat.rs

@@ -1,7 +1,5 @@
 //! Matrix with dimensions unknown at compile-time.
 
-#![allow(missing_docs)] // we hide doc to not have to document the $trhs double dispatch trait.
-
 use std::cmp;
 use std::mem;
 use std::iter::repeat;
@@ -131,6 +129,7 @@ impl<N> DMat<N> {
 dmat_impl!(DMat, DVec);
 
 
+/// A stack-allocated dynamically sized matrix with at most one row and column.
 pub struct DMat1<N> {
     nrows: usize,
     ncols: usize,
@@ -141,6 +140,7 @@ small_dmat_impl!(DMat1, DVec1, 1, 0);
 small_dmat_from_impl!(DMat1, 1, ::zero());
 
 
+/// A stack-allocated dynamically sized square or rectangular matrix with at most 2 rows and columns.
 pub struct DMat2<N> {
     nrows: usize,
     ncols: usize,
@@ -153,6 +153,7 @@ small_dmat_from_impl!(DMat2, 2, ::zero(), ::zero(),
                                 ::zero(), ::zero());
 
 
+/// A stack-allocated dynamically sized square or rectangular matrix with at most 3 rows and columns.
 pub struct DMat3<N> {
     nrows: usize,
     ncols: usize,
@@ -167,6 +168,7 @@ small_dmat_from_impl!(DMat3, 3, ::zero(), ::zero(), ::zero(),
                                 ::zero(), ::zero(), ::zero());
 
 
+/// A stack-allocated dynamically sized square or rectangular matrix with at most 4 rows and columns.
 pub struct DMat4<N> {
     nrows: usize,
     ncols: usize,
@@ -183,6 +185,7 @@ small_dmat_from_impl!(DMat4, 4, ::zero(), ::zero(), ::zero(), ::zero(),
                                 ::zero(), ::zero(), ::zero(), ::zero());
 
 
+/// A stack-allocated dynamically sized square or rectangular matrix with at most 5 rows and columns.
 pub struct DMat5<N> {
     nrows: usize,
     ncols: usize,
@@ -201,6 +204,7 @@ small_dmat_from_impl!(DMat5, 5, ::zero(), ::zero(), ::zero(), ::zero(), ::zero()
                                 ::zero(), ::zero(), ::zero(), ::zero(), ::zero());
 
 
+/// A stack-allocated dynamically sized square or rectangular matrix with at most 6 rows and columns.
 pub struct DMat6<N> {
     nrows: usize,
     ncols: usize,

src/structs/dmat_macros.rs

@@ -19,6 +19,7 @@ macro_rules! dmat_impl(
                 self.mij.iter().all(|e| e.is_zero())
             }
 
+            /// Set this matrix components to zero.
             #[inline]
             pub fn reset(&mut self) {
                 for mij in self.mij.iter_mut() {
@@ -881,7 +882,8 @@ macro_rules! small_dmat_from_impl(
             }
         }
 
-        impl<N> $dmat<N> {
+        impl<N: Copy> $dmat<N> {
+            /// Creates a new matrix with uninitialized components (with `mem::uninitialized()`).
             #[inline]
             pub unsafe fn new_uninitialized(nrows: usize, ncols: usize) -> $dmat<N> {
                 assert!(nrows <= $dim);

src/structs/dvec.rs

@@ -1,7 +1,5 @@
 //! Vector with dimensions unknown at compile-time.
 
-#![allow(missing_docs)] // we hide doc to not have to document the $trhs double dispatch trait.
-
 use std::slice::{Iter, IterMut};
 use std::iter::{FromIterator, IntoIterator};
 use std::iter::repeat;

src/structs/pnt.rs

@@ -1,7 +1,5 @@
 //! Points with dimension known at compile-time.
 
-#![allow(missing_docs)] // we allow missing to avoid having to document the point components.
-
 use std::mem;
 use std::slice::{Iter, IterMut};
 use std::iter::{Iterator, FromIterator, IntoIterator};

src/structs/quat.rs

@@ -1,7 +1,5 @@
 //! Quaternion definition.
 
-#![allow(missing_docs)] // we allow missing to avoid having to document the dispatch trait.
-
 use std::mem;
 use std::slice::{Iter, IterMut};
 use std::ops::{Add, Sub, Mul, Div, Neg, Index, IndexMut};

src/structs/rot.rs

@@ -1,7 +1,5 @@
 //! Rotations matrices.
 
-#![allow(missing_docs)]
-
 use std::ops::{Mul, Neg, Index};
 use rand::{Rand, Rng};
 use num::{Zero, One};

src/structs/rot_macros.rs

@@ -3,6 +3,7 @@
 macro_rules! submat_impl(
     ($t: ident, $submat: ident) => (
         impl<N> $t<N> {
+            /// This rotation's underlying matrix.
             #[inline]
             pub fn submat<'r>(&'r self) -> &'r $submat<N> {
                 &self.submat

src/structs/vec.rs

@@ -1,7 +1,5 @@
 //! Vectors with dimension known at compile-time.
 
-#![allow(missing_docs)] // we allow missing to avoid having to document the dispatch traits.
-
 use std::ops::{Add, Sub, Mul, Div, Neg, Index, IndexMut};
 use std::mem;
 use std::slice::{Iter, IterMut};

src/structs/vec_macros.rs

@@ -278,6 +278,7 @@ macro_rules! dim_impl(
 macro_rules! container_impl(
     ($t: ident) => (
         impl<N> $t<N> {
+            /// The dimension of this entity.
             #[inline]
             pub fn len(&self) -> usize {
                 Dim::dim(None::<$t<N>>)
@@ -298,8 +299,8 @@ macro_rules! basis_impl(
 
             #[inline]
             fn orthonormal_subspace_basis<F: FnMut($t<N>) -> bool>(n: &$t<N>, mut f: F) {
-                // compute the basis of the orthogonal subspace using Gram-Schmidt
-                // orthogonalization algorithm
+                // Compute the basis of the orthogonal subspace using Gram-Schmidt
+                // orthogonalization algorithm.
                 let mut basis: Vec<$t<N>> = Vec::new();
 
                 for i in 0 .. $dim {
@@ -743,6 +744,7 @@ macro_rules! transform_impl(
 macro_rules! vec_as_pnt_impl(
     ($tv: ident, $t: ident, $($compN: ident),+) => (
         impl<N> $tv<N> {
+            /// Converts this vector to a point.
             #[inline]
             pub fn to_pnt(self) -> $t<N> {
                 $t::new(
@@ -750,6 +752,7 @@ macro_rules! vec_as_pnt_impl(
                 )
             }
 
+            /// Reinterprets this vector as a point.
             #[inline]
             pub fn as_pnt(&self) -> &$t<N> {
                 unsafe {