Explain l1 and l2 norms.

nalgebra-glm/src/gtx/norm.rs

@@ -14,24 +14,67 @@ pub fn distance2<N: Real, D: Dimension>(p0: &TVec<N, D>, p1: &TVec<N, D>) -> N
 }
 
 /// The l1-norm of `x - y`.
+///
+/// # See also:
+///
+/// * [`l1_norm`](fn.l1_norm.html)
+/// * [`l2_distance`](fn.l2_distance.html)
+/// * [`l2_norm`](fn.l2_norm.html)
 pub fn l1_distance<N: Real, D: Dimension>(x: &TVec<N, D>, y: &TVec<N, D>) -> N
     where DefaultAllocator: Alloc<N, D> {
     l1_norm(&(y - x))
 }
 
 /// The l1-norm of `v`.
+///
+/// This is also known as the "Manhattan distance" or "taxicab distance" and
+/// corresponds to the sum of the absolute values of the components of `v`.
+///
+/// # See also:
+///
+/// * [`l1_distance`](fn.l1_distance.html)
+/// * [`l2_distance`](fn.l2_distance.html)
+/// * [`l2_norm`](fn.l2_norm.html)
 pub fn l1_norm<N: Real, D: Dimension>(v: &TVec<N, D>) -> N
     where DefaultAllocator: Alloc<N, D> {
     ::comp_add(&v.abs())
 }
 
 /// The l2-norm of `x - y`.
+///
+/// This is the same value as returned by [`length2`](fn.length2.html) and
+/// [`magnitude2`](fn.magnitude2.html).
+///
+/// # See also:
+///
+/// * [`l1_distance`](fn.l1_distance.html)
+/// * [`l1_norm`](fn.l1_norm.html)
+/// * [`l2_norm`](fn.l2_norm.html)
+/// * [`length`](fn.length.html)
+/// * [`length2`](fn.length2.html)
+/// * [`magnitude`](fn.magnitude.html)
+/// * [`magnitude2`](fn.magnitude2.html)
 pub fn l2_distance<N: Real, D: Dimension>(x: &TVec<N, D>, y: &TVec<N, D>) -> N
     where DefaultAllocator: Alloc<N, D> {
     l2_norm(&(y - x))
 }
 
 /// The l2-norm of `v`.
+///
+/// This is also known as the Euclidean norm.
+///
+/// This is the same value as returned by [`length`](fn.length.html) and
+/// [`magnitude`](fn.magnitude.html).
+///
+/// # See also:
+///
+/// * [`l1_distance`](fn.l1_distance.html)
+/// * [`l1_norm`](fn.l1_norm.html)
+/// * [`l2_distance`](fn.l2_distance.html)
+/// * [`length`](fn.length.html)
+/// * [`length2`](fn.length2.html)
+/// * [`magnitude`](fn.magnitude.html)
+/// * [`magnitude2`](fn.magnitude2.html)
 pub fn l2_norm<N: Real, D: Dimension>(x: &TVec<N, D>) -> N
     where DefaultAllocator: Alloc<N, D> {
     x.norm()