From e88da58a87a487545c0c820077fa2dc2df654cdf Mon Sep 17 00:00:00 2001
From: Dimitri Sabadie <dimitri.sabadie@gmail.com>
Date: Tue, 23 Apr 2019 14:12:08 +0200
Subject: [PATCH] Step 3 of doc cleanup.

---
 src/key.rs    | 17 +++++++++++++----
 src/spline.rs | 26 ++++++++++++++++++++------
 2 files changed, 33 insertions(+), 10 deletions(-)

diff --git a/src/key.rs b/src/key.rs
index 8abbd2c..ced101e 100644
--- a/src/key.rs
+++ b/src/key.rs
@@ -1,3 +1,11 @@
+//! Spline control points.
+//!
+//! A control point associates to a “sampling value” (a.k.a. time) a carriede value that can be
+//! interpolated along the curve made by the control points.
+//!
+//! Splines constructed with this crate have the property that it’s possible to change the
+//! interpolation mode on a key-based way, allowing you to implement and encode complex curves.
+
 #[cfg(feature = "serialization")] use serde_derive::{Deserialize, Serialize};
 
 use crate::interpolation::Interpolation;
@@ -5,15 +13,17 @@ use crate::interpolation::Interpolation;
 /// A spline control point.
 ///
 /// This type associates a value at a given interpolation parameter value. It also contains an
-/// interpolation hint used to determine how to interpolate values on the segment defined by this
-/// key and the next one – if existing.
+/// interpolation mode used to determine how to interpolate values on the segment defined by this
+/// key and the next one – if existing. Have a look at [`Interpolation`] for further details.
+///
+/// [`Interpolation`]: crate::interpolation::Interpolation
 #[derive(Copy, Clone, Debug)]
 #[cfg_attr(feature = "serialization", derive(Deserialize, Serialize))]
 #[cfg_attr(feature = "serialization", serde(rename_all = "snake_case"))]
 pub struct Key<T, V> {
   /// Interpolation parameter at which the [`Key`] should be reached.
   pub t: T,
-  /// Held value.
+  /// Carried value.
   pub value: V,
   /// Interpolation mode.
   pub interpolation: Interpolation<T>
@@ -25,4 +35,3 @@ impl<T, V> Key<T, V> {
     Key { t, value, interpolation }
   }
 }
-
diff --git a/src/spline.rs b/src/spline.rs
index fa096c4..a7e0379 100644
--- a/src/spline.rs
+++ b/src/spline.rs
@@ -1,3 +1,5 @@
+//! Spline curves and operations.
+
 #[cfg(feature = "serialization")] use serde_derive::{Deserialize, Serialize};
 #[cfg(not(feature = "std"))] use alloc::vec::Vec;
 #[cfg(feature = "std")] use std::cmp::Ordering;
@@ -10,6 +12,17 @@ use crate::interpolation::Interpolation;
 use crate::key::Key;
 
 /// Spline curve used to provide interpolation between control points (keys).
+///
+/// Splines are made out of control points ([`Key`]). When creating a [`Spline`] with
+/// [`Spline::from_vec`] or [`Spline::from_iter`], the keys don’t have to be sorted (they are sorted
+/// automatically by the sampling value).
+///
+/// You can sample from a spline with several functions:
+///
+///   - [`Spline::sample`]: allows you to sample from a spline. If not enough keys are available
+///     for the required interpolation mode, you get `None`.
+///   - [`Spline::clamped_sample`]: behaves like [`Spline::sample`] but will return either the first
+///     or last key if out of bound; it will return `None` if not enough key.
 #[derive(Debug, Clone)]
 #[cfg_attr(feature = "serialization", derive(Deserialize, Serialize))]
 pub struct Spline<T, V>(pub(crate) Vec<Key<T, V>>);
@@ -29,7 +42,7 @@ impl<T, V> Spline<T, V> {
   /// # Note on iterators
   ///
   /// It’s valid to use any iterator that implements `Iterator<Item = Key<T>>`. However, you should
-  /// use `Spline::from_vec` if you are passing a `Vec<_>`. This will remove dynamic allocations.
+  /// use [`Spline::from_vec`] if you are passing a [`Vec`]. This will remove dynamic allocations.
   pub fn from_iter<I>(iter: I) -> Self where I: Iterator<Item = Key<T, V>>, T: PartialOrd {
     Self::from_vec(iter.collect())
   }
@@ -50,9 +63,10 @@ impl<T, V> Spline<T, V> {
   ///
   /// `None` if you try to sample a value at a time that has no key associated with. That can also
   /// happen if you try to sample between two keys with a specific interpolation mode that makes the
-  /// sampling impossible. For instance, `Interpolate::CatmullRom` requires *four* keys. If you’re
-  /// near the beginning of the spline or its end, ensure you have enough keys around to make the
-  /// sampling.
+  /// sampling impossible. For instance, [`Interpolation::CatmullRom`] requires *four* keys. If
+  /// you’re near the beginning of the spline or its end, ensure you have enough keys around to make
+  /// the sampling.
+  ///
   pub fn sample(&self, t: T) -> Option<V>
   where T: Additive + One + Trigo + Mul<T, Output = T> + Div<T, Output = T> + PartialOrd,
         V: Interpolate<T> {
@@ -105,11 +119,11 @@ impl<T, V> Spline<T, V> {
   /// # Return
   ///
   /// If you sample before the first key or after the last one, return the first key or the last
-  /// one, respectively. Otherwise, behave the same way as `Spline::sample`.
+  /// one, respectively. Otherwise, behave the same way as [`Spline::sample`].
   ///
   /// # Error
   ///
-  /// This function returns `None` if you have no key.
+  /// This function returns [`None`] if you have no key.
   pub fn clamped_sample(&self, t: T) -> Option<V>
   where T: Additive + One + Trigo + Mul<T, Output = T> + Div<T, Output = T> + PartialOrd,
         V: Interpolate<T> {