From 651d318c26566ceac9062cd0b3f9be2d27eb92c3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Crozet=20S=C3=A9bastien?= <developer@crozet.re>
Date: Sat, 21 Nov 2020 12:19:04 +0100
Subject: [PATCH] Add sections to the Unit wrapper documentation

---
 src/base/interpolation.rs |  1 +
 src/base/unit.rs          | 11 ++++++++++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/src/base/interpolation.rs b/src/base/interpolation.rs
index afd3ccc7..1d74d203 100644
--- a/src/base/interpolation.rs
+++ b/src/base/interpolation.rs
@@ -56,6 +56,7 @@ impl<N: Scalar + Zero + One + ClosedAdd + ClosedSub + ClosedMul, D: Dim, S: Stor
     }
 }
 
+/// # Interpolation between two unit vectors
 impl<N: RealField, D: Dim, S: Storage<N, D>> Unit<Vector<N, D, S>> {
     /// Computes the spherical linear interpolation between two unit vectors.
     ///
diff --git a/src/base/unit.rs b/src/base/unit.rs
index 5afa006b..20ca4603 100644
--- a/src/base/unit.rs
+++ b/src/base/unit.rs
@@ -15,7 +15,14 @@ use crate::{Dim, MatrixMN, RealField, Scalar, SimdComplexField, SimdRealField};
 
 /// A wrapper that ensures the underlying algebraic entity has a unit norm.
 ///
-/// Use `.as_ref()` or `.into_inner()` to obtain the underlying value by-reference or by-move.
+/// **It is likely that the only piece of documentation that you need in this page are:**
+/// - **[The construction with normalization](#construction-with-normalization)**
+/// - **[Data extraction and construction without normalization](#data-extraction-and-construction-without-normalization)**
+/// - **[Interpolation between two unit vectors](#interpolation-between-two-unit-vectors)**
+///
+/// All the other impl blocks you will see in this page are about [`UnitComplex`](crate::UnitComplex)
+/// and [`UnitQuaternion`](crate::UnitQuaternion); both built on top of `Unit`.  If you are interested
+/// in their documentation, read their dedicated pages directly.
 #[repr(transparent)]
 #[derive(Eq, PartialEq, Clone, Hash, Debug, Copy)]
 pub struct Unit<T> {
@@ -71,6 +78,7 @@ pub trait Normed {
     fn unscale_mut(&mut self, n: Self::Norm);
 }
 
+/// # Construction with normalization
 impl<T: Normed> Unit<T> {
     /// Normalize the given vector and return it wrapped on a `Unit` structure.
     #[inline]
@@ -140,6 +148,7 @@ impl<T: Normed> Unit<T> {
     }
 }
 
+/// # Data extraction and construction without normalization
 impl<T> Unit<T> {
     /// Wraps the given value, assuming it is already normalized.
     #[inline]