[libadwaita/wip/exalm/spring-animation-swipes: 28/36] wip docs

[Alexander Mikhaylenko <alexm src gnome org>]

commit 61ed66d3c54e49b822be93657de8f8aa33a97618
Author: Manuel Genovés <manuel genoves gmail com>
Date:   Mon Dec 6 00:49:34 2021 +0100

    wip docs

 src/adw-spring-animation.c | 64 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)
---
diff --git a/src/adw-spring-animation.c b/src/adw-spring-animation.c
index 48dad1b3..26e36630 100644
--- a/src/adw-spring-animation.c
+++ b/src/adw-spring-animation.c
@@ -14,6 +14,50 @@
 
 #define DELTA 0.001
 
+/**
+ * AdwSpringAnimation:
+ *
+ * A spring-based [class@Adw.Animation].
+ *
+ * `AdwSpringAnimation` implements an animation driven by a physical model of a 
+ * spring characterized by [class@Adw.SpringParams], with a resting position in
+ * [property@Adw.SpringAnimation:value-to], stretched to
+ * [property@Adw.SpringAnimation:value-from].
+ * 
+ * Since the animation is physically simulated, spring animations don't have a
+ * fixed duration. The animation will stop when the simulated spring comes to a
+ * rest - when the amplitude of the oscillations becomes smaller than
+ * [property@Adw.SpringAnimation:epsilon], or the first time it reaches 
+ * [property@Adw.SpringAnimation:value-to] if [property@Adw.SpringAnimation:clamp]
+ * is True. The estimated duration can be obtained with 
+ * [property@Adw.SpringAnimation:estimated-duration].
+ *
+ * Due to the nature of spring-driven motion the animation can overshoot
+ * [property@Adw.SpringAnimation:value-to] before coming to a rest. Whether the
+ * animation will overshoot or not depends on the
+ * [property@Adw.SpringParams:damping-ratio] of the spring:
+ *
+ * * If the value is 1, the spring is critically damped and will reach its
+ *   resting position the quickest way possible.
+ * * If the value is 0, the spring will not be damped and will oscillate
+ *   endlessly.
+ * * If the value is between 0 and 1, the spring is underdamped and will always
+ *   overshoot.
+ * 
+ * If [property@Adw.SpringAnimation:clamp] is True the animation will never overshoot
+ * and will stop the moment it reaches [property@Adw.SpringAnimation:value-to].
+ *
+ * Animations can have an initial velocity value, set via
+ * [property@Adw.SpringAnimation:initial-velocity], which doesn't change the
+ * estimated duration but adjusts the curve. This makes spring animations useful
+ * as deceleration at the end of gestures.
+ *
+ * If the initial and final values are equal, and the [property@Adw.SpringAnimation:initial-velocity]
+ * is not 0, the animation value will bounce and return to its resting position.
+ *
+ * Since: 1.0
+ */
+
 struct _AdwSpringAnimation
 {
   AdwAnimation parent_instance;
@@ -347,6 +391,16 @@ adw_spring_animation_class_init (AdwSpringAnimationClass *klass)
   animation_class->estimate_duration = adw_spring_animation_estimate_duration;
   animation_class->calculate_value = adw_spring_animation_calculate_value;
 
+  /**
+   * AdwSpringAnimation:value-from: (attributes org.gtk.Property.get=adw_spring_animation_get_value_from 
org.gtk.Property.set=adw_spring_animation_set_value_from)
+   *
+   * The value to animate from.
+   *
+   * The animation will start at this value and end at
+   * [property@Adw.SpringAnimation:value-to].
+   *
+   * Since: 1.0
+   */
   props[PROP_VALUE_FROM] =
     g_param_spec_double ("value-from",
                          "Initial value",
@@ -356,6 +410,16 @@ adw_spring_animation_class_init (AdwSpringAnimationClass *klass)
                          0,
                          G_PARAM_READWRITE | G_PARAM_CONSTRUCT);
 
+  /**
+   * AdwSpringAnimation:value-to: (attributes org.gtk.Property.get=adw_spring_animation_get_value_to 
org.gtk.Property.set=adw_spring_animation_set_value_to)
+   *
+   * The value to animate to.
+   *
+   * The animation will start at [property@Adw.SpringAnimation:value-from and
+   * end at this value.
+   *
+   * Since: 1.0
+   */
   props[PROP_VALUE_TO] =
     g_param_spec_double ("value-to",
                          "Final value",