From e91ed3b0cddde021b91ee1c93cc7355e713b4ccc Mon Sep 17 00:00:00 2001
From: Bruce Mitchener <bruce.mitchener@gmail.com>
Date: Mon, 8 Oct 2018 21:56:58 +0700
Subject: [PATCH] Explain l1 and l2 norms.

---
 nalgebra-glm/src/gtx/norm.rs | 43 ++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/nalgebra-glm/src/gtx/norm.rs b/nalgebra-glm/src/gtx/norm.rs
index cde4d5c7..2a40c02a 100644
--- a/nalgebra-glm/src/gtx/norm.rs
+++ b/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()