From e97c200dbe8be05c7056459267d6a0e19c86844f Mon Sep 17 00:00:00 2001
From: Jerome Humbert <djeedai@gmail.com>
Date: Mon, 29 Apr 2024 20:40:12 +0100
Subject: [PATCH] Improve some docs (#126)

---
 src/lib.rs | 52 +++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 43 insertions(+), 9 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 2b3b64b..aae1fc8 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -228,12 +228,23 @@ mod tweenable;
 #[cfg(test)]
 mod test_utils;
 
-/// How many times to repeat a tween animation. See also: [`RepeatStrategy`].
+/// How many times to repeat a tweenable animation.
+///
+/// See also [`RepeatStrategy`].
+///
+/// Default: `Finite(1)`
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum RepeatCount {
-    /// Run the animation N times.
+    /// Run the animation an exact number of times.
+    ///
+    /// The total playback duration is the tweenable animation duration times
+    /// this number of iterations.
     Finite(u32),
-    /// Run the animation for some amount of time.
+    /// Run the animation for some duration.
+    ///
+    /// If this duration is not a multiple of the tweenable animation duration,
+    /// then the animation will get stopped midway through its playback,
+    /// possibly even before finishing a single loop.
     For(Duration),
     /// Loop the animation indefinitely.
     Infinite,
@@ -257,13 +268,18 @@ impl From<Duration> for RepeatCount {
     }
 }
 
-/// What to do when a tween animation needs to be repeated. See also
-/// [`RepeatCount`].
+/// What to do when a tween animation needs to be repeated.
 ///
 /// Only applicable when [`RepeatCount`] is greater than the animation duration.
+///
+/// Default: `Repeat`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum RepeatStrategy {
     /// Reset the animation back to its starting position.
+    ///
+    /// When playback reaches the end of the animation, it jumps directly back
+    /// to the animation start. This can create discontinuities if the animation
+    /// is not authored to be looping.
     Repeat,
     /// Follow a ping-pong pattern, changing the direction each time an endpoint
     /// is reached.
@@ -272,6 +288,9 @@ pub enum RepeatStrategy {
     /// iterations for the various operations where looping matters. That
     /// is, a 1 second animation will take 2 seconds to end up back where it
     /// started.
+    ///
+    /// This strategy ensures that there's no discontinuity in the animation,
+    /// since there's no jump.
     MirroredRepeat,
 }
 
@@ -282,6 +301,8 @@ impl Default for RepeatStrategy {
 }
 
 /// Playback state of an animator.
+///
+/// Default: `Playing`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum AnimatorState {
     /// The animation is playing. This is the default state.
@@ -308,14 +329,25 @@ impl std::ops::Not for AnimatorState {
 }
 
 /// Describe how eased value should be computed.
+///
+/// This function is applied to the animation fraction `t` representing the
+/// playback position over the animation duration. The result is used to
+/// interpolate the animator target.
+///
+/// In general a [`Lens`] should perform a linear interpolation over its target,
+/// and the non-linear behavior (for example, bounciness, etc.) comes from this
+/// function. This ensures the same [`Lens`] can be reused in multiple contexts,
+/// while the "shape" of the animation is controlled independently.
+///
+/// Default: `Linear`.
 #[derive(Clone, Copy)]
 pub enum EaseMethod {
-    /// Follow `EaseFunction`.
+    /// Follow [`EaseFunction`].
     EaseFunction(EaseFunction),
-    /// Linear interpolation, with no function.
+    /// Linear interpolation.
     Linear,
-    /// Discrete interpolation, eased value will jump from start to end when
-    /// stepping over the discrete limit.
+    /// Discrete interpolation. The eased value will jump from start to end when
+    /// stepping over the discrete limit, which must be value between 0 and 1.
     Discrete(f32),
     /// Use a custom function to interpolate the value.
     CustomFunction(fn(f32) -> f32),
@@ -367,6 +399,8 @@ impl From<EaseFunction> for EaseMethod {
 /// value set. When using [`RepeatStrategy::MirroredRepeat`], this is either
 /// forward (from start to end; ping) or backward (from end to start; pong),
 /// depending on the current iteration of the loop.
+///
+/// Default: `Forward`.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum TweeningDirection {
     /// Animation playing from start to end.