From c344be735151b51a3afc2c019a5003a298272143 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Crozet?= <developer@crozet.re>
Date: Thu, 26 Sep 2013 17:18:14 +0200
Subject: [PATCH] Minor doc improvements.

---
 src/lib.rs               | 10 +---------
 src/traits/geometry.rs   |  9 +++++++--
 src/traits/operations.rs | 13 +++++++++----
 src/traits/structure.rs  |  2 ++
 src/vec.rs               |  2 +-
 5 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 04b0ee42..9c62ecd2 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -28,18 +28,10 @@ pub mod adaptors {
     pub mod transform;
 }
 
-/// Traits implemented by matrices and vectors.
-/// 
-/// They should not be imported from here since all of them are re-exported by the `mat` or the
-/// `vec` module.
+/// Traits implemented by matrices and vectors. Re-exported by the `mat` or the `vec` module.
 pub mod traits {
-    /// Traits of operations having a well-known or explicit geometric meaning.
     pub mod geometry;
-
-    /// Traits giving structural informations on linear algebra objects or the space they live in.
     pub mod structure;
-
-    /// Low level operations on vectors and matrices.
     pub mod operations;
 }
 
diff --git a/src/traits/geometry.rs b/src/traits/geometry.rs
index 7a80ec59..d1096595 100644
--- a/src/traits/geometry.rs
+++ b/src/traits/geometry.rs
@@ -1,3 +1,6 @@
+//! Traits of operations having a well-known or explicit geometric meaning.
+
+
 use traits::structure::Mat;
 
 /// Trait of object which represent a translation, and to wich new translation
@@ -105,9 +108,11 @@ pub trait Dot<N> {
     /**
      * Short-cut to compute the projection of a point on a vector, but without
      * computing intermediate vectors.
-     * This must be equivalent to:
+     * The following equation must be verified:
      *
-     *   (a - b).dot(c)
+     * ~~~{.rust}
+     *   a.sub_dot(b, c) == (a - b).dot(c)
+     * ~~~
      *
      */
     #[inline]
diff --git a/src/traits/operations.rs b/src/traits/operations.rs
index 4575a8fa..e26f2d49 100644
--- a/src/traits/operations.rs
+++ b/src/traits/operations.rs
@@ -1,3 +1,6 @@
+//! Low level operations on vectors and matrices.
+
+
 /// Trait of objects having an absolute value.
 /// This is useful if the object does not have the same type as its absolute value.
 pub trait Absolute<A> {
@@ -34,16 +37,18 @@ pub trait Outer<V, M> {
 /// Trait for computing the covariance of a set of data.
 pub trait Cov<M> {
     /// Computes the covariance of the obsevations stored by `self`:
-    ///     * for matrices, observations are stored in its rows.
-    ///     * for vectors, observations are stored in its components (thus are 1-dimensional).
+    ///
+    ///   * For matrices, observations are stored in its rows.
+    ///   * For vectors, observations are stored in its components (thus are 1-dimensional).
     fn cov(&self) -> M;
 }
 
 /// Trait for computing the covariance of a set of data.
 pub trait Mean<N> {
     /// Computes the mean of the observations stored by `self`.
-    ///     * for matrices, observations are stored in its rows.
-    ///     * for vectors, observations are stored in its components (thus are 1-dimensional).
+    /// 
+    ///   * For matrices, observations are stored in its rows.
+    ///   * For vectors, observations are stored in its components (thus are 1-dimensional).
     fn mean(&self) -> N;
 }
 
diff --git a/src/traits/structure.rs b/src/traits/structure.rs
index 77c04979..2343acd3 100644
--- a/src/traits/structure.rs
+++ b/src/traits/structure.rs
@@ -1,3 +1,5 @@
+//! Traits giving structural informations on linear algebra objects or the space they live in.
+
 use std::num::Zero;
 use std::vec::{VecIterator, VecMutIterator};
 use traits::operations::{RMul, LMul, ScalarAdd, ScalarSub};
diff --git a/src/vec.rs b/src/vec.rs
index aa159bf3..1d82357a 100644
--- a/src/vec.rs
+++ b/src/vec.rs
@@ -1,6 +1,6 @@
 //! Vectors with dimensions known at compile-time.
 
-#[doc(hidden)]; // we hide doc to not have to document the $trhs double dispatch trait.
+#[allow(missing_doc)]; // we allow missing to avoid having to document the vector components.
 
 use std::cast;
 use std::num::{Zero, One, Algebraic, Bounded};