From e7ecc9819ab0835c48ceb596b808625d04f64ba0 Mon Sep 17 00:00:00 2001
From: Dimitri Sabadie <dimitri.sabadie@gmail.com>
Date: Tue, 23 Apr 2019 14:22:16 +0200
Subject: [PATCH] Documentation, step 4.

---
 src/interpolate.rs | 30 ++++++++++++++++++++----------
 src/lib.rs         | 11 +++++++++--
 2 files changed, 29 insertions(+), 12 deletions(-)

diff --git a/src/interpolate.rs b/src/interpolate.rs
index 956c972..05c9408 100644
--- a/src/interpolate.rs
+++ b/src/interpolate.rs
@@ -3,13 +3,22 @@
 //! The [`Interpolate`] trait is the central concept of the crate. It enables a spline to be
 //! sampled at by interpolating in between control points.
 //!
-//! In order for a type to be used in [`Spline<K, V>`], some properties must be met:
+//! In order for a type to be used in [`Spline<K, V>`], some properties must be met about the `K`
+//! type must implementing several traits:
 //!
-//!   - The `K` type must implement several traits:
-//!     - [`One`], giving a neutral element for the multiplication monoid.
-//!     - [`Additive`], making the type additive (i.e. one can add or subtract with it).
-//!     - [`Linear`], unlocking linear combinations, required for interpolating.
-//!     - [`Trigo`], a trait giving *π* and *cosine*, required for e.g. cosine interpolation.
+//!   - [`One`], giving a neutral element for the multiplication monoid.
+//!   - [`Additive`], making the type additive (i.e. one can add or subtract with it).
+//!   - [`Linear`], unlocking linear combinations, required for interpolating.
+//!   - [`Trigo`], a trait giving *π* and *cosine*, required for e.g. cosine interpolation.
+//!
+//! Feel free to have a look at current implementors for further help.
+//!
+//! > *Why doesn’t this crate use [num-traits] instead of
+//! > defining its own traits?*
+//!
+//! The reason for this is quite simple: this crate provides a `no_std` support, which is not
+//! currently available easily with [num-traits]. Also, if something changes in [num-traits] with
+//! those traits, it would make this whole crate unstable.
 //!
 //! [`Interpolate`]: crate::interpolate::Interpolate
 //! [`Spline<K, V>`]: crate::spline::Spline
@@ -17,6 +26,7 @@
 //! [`Additive`]: crate::interpolate::Additive
 //! [`Linear`]: crate::interpolate::Linear
 //! [`Trigo`]: crate::interpolate::Trigo
+//! [num-traits]: https://crates.io/crates/num-traits
 
 #[cfg(feature = "std")] use std::f32;
 #[cfg(not(feature = "std"))] use core::f32;
@@ -178,10 +188,10 @@ impl Trigo for f64 {
   }
 }
 
-// Default implementation of Interpolate::cubic_hermite`.
-//
-// `V` is the value being interpolated. `T` is the sampling value (also sometimes called time).
-pub(crate) fn cubic_hermite_def<V, T>(x: (V, T), a: (V, T), b: (V, T), y: (V, T), t: T) -> V
+/// Default implementation of [`Interpolate::cubic_hermite`].
+///
+/// `V` is the value being interpolated. `T` is the sampling value (also sometimes called time).
+pub fn cubic_hermite_def<V, T>(x: (V, T), a: (V, T), b: (V, T), y: (V, T), t: T) -> V
 where V: Linear<T>,
       T: Additive + Mul<T, Output = T> + One {
   // some stupid generic constants, because Rust doesn’t have polymorphic literals…
diff --git a/src/lib.rs b/src/lib.rs
index 2ca01c5..a567dd4 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -33,11 +33,11 @@
 //! # Interpolate values
 //!
 //! The whole purpose of splines is to interpolate discrete values to yield continuous ones. This is
-//! usually done with the `Spline::sample` method. This method expects the interpolation parameter
+//! usually done with the [`Spline::sample`] method. This method expects the sampling parameter
 //! (often, this will be the time of your simulation) as argument and will yield an interpolated
 //! value.
 //!
-//! If you try to sample in out-of-bounds interpolation parameter, you’ll get no value.
+//! If you try to sample in out-of-bounds sampling parameter, you’ll get no value.
 //!
 //! ```
 //! # use splines::{Interpolation, Key, Spline};
@@ -62,6 +62,13 @@
 //! assert_eq!(spline.clamped_sample(1.1), Some(10.)); // clamped to the last key
 //! ```
 //!
+//! # Polymorphic sampling types
+//!
+//! [`Spline`] curves are parametered both by the carried value (being interpolated) but also the
+//! sampling type. It’s very typical to use `f32` or `f64` but really, you can in theory use any
+//! kind of type; that type must, however, implement a contract defined by a set of traits to
+//! implement. See [the documentation of this module](crate::interpolate) for further details.
+//!
 //! # Features and customization
 //!
 //! This crate was written with features baked in and hidden behind feature-gates. The idea is that