Improve some docs (#126)

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.