[animation] Enhance consistency of the Animation API

The Animation API should follow this pattern:

  - functions with an Interval as part of the arguments should have
    "interval" inside their name, e.g.:

      clutter_animation_bind_interval
      clutter_animation_update_interval

  - functions dealing with property names should have "property"
    inside their name, e.g.:

      clutter_animation_has_property
      clutter_animation_unbind_property

    - unless -

  - functions dealing with a property and its value should not
    have any modifier, e.g.:

      clutter_animation_bind

The change from update_property() to update_interval() frees up
clutter_animation_update(), to be added at a later date.

clutter/clutter-animation.c

@@ -633,7 +633,7 @@ clutter_animation_has_property (ClutterAnimation *animation,
 }
 
 /**
- * clutter_animation_update_property:
+ * clutter_animation_update_interval:
  * @animation: a #ClutterAnimation
  * @property_name: name of the property
  * @interval: a #ClutterInterval
@@ -644,7 +644,7 @@ clutter_animation_has_property (ClutterAnimation *animation,
  * Since: 1.0
  */
 void
-clutter_animation_update_property (ClutterAnimation *animation,
+clutter_animation_update_interval (ClutterAnimation *animation,
                                    const gchar      *property_name,
                                    ClutterInterval  *interval)
 {
@@ -812,6 +812,29 @@ on_animation_weak_notify (gpointer  data,
   g_object_set_qdata (actor, quark_object_animation, NULL);
 }
 
+/**
+ * clutter_animation_new:
+ *
+ * Creates a new #ClutterAnimation instance. You should set the
+ * #GObject to be animated using clutter_animation_set_object(),
+ * set the duration with clutter_animation_set_duration() and the
+ * easing mode using clutter_animation_set_mode().
+ *
+ * Use clutter_animation_bind() or clutter_animation_bind_interval()
+ * to define the properties to be animated. The interval and the
+ * animated properties can be updated at runtime.
+ *
+ * The clutter_actor_animate() and relative family of functions provide
+ * an easy way to animate a #ClutterActor and automatically manage the
+ * lifetime of a #ClutterAnimation instance, so you should consider using
+ * those functions instead of manually creating an animation.
+ *
+ * Return value: the newly created #ClutterAnimation. Use g_object_ref_sink()
+ *   to take ownership of the Animation instance, and g_object_unref() to
+ *   release the associated resources
+ *
+ * Since: 1.0
+ */
 ClutterAnimation *
 clutter_animation_new (void)
 {

clutter/clutter-animation.h

@@ -124,10 +124,10 @@ ClutterAnimation *   clutter_animation_bind_interval   (ClutterAnimation     *an
                                                         ClutterInterval      *interval);
 gboolean             clutter_animation_has_property    (ClutterAnimation     *animation,
                                                         const gchar          *property_name);
-void                 clutter_animation_update_property (ClutterAnimation     *animation,
+void                 clutter_animation_update_interval (ClutterAnimation     *animation,
                                                         const gchar          *property_name,
                                                         ClutterInterval      *interval);
-void                 clutter_animation_unbind          (ClutterAnimation     *animation,
+void                 clutter_animation_unbind_property (ClutterAnimation     *animation,
                                                         const gchar          *property_name);
 ClutterInterval     *clutter_animation_get_interval    (ClutterAnimation     *animation,
                                                         const gchar          *property_name);

doc/reference/clutter/clutter-sections.txt

@@ -1417,9 +1417,9 @@ clutter_animation_completed
 <SUBSECTION>
 clutter_animation_bind
 clutter_animation_bind_interval
-clutter_animation_update_property
+clutter_animation_update_interval
 clutter_animation_has_property
-clutter_animation_unbind
+clutter_animation_unbind_property
 clutter_animation_get_interval
 
 <SUBSECTION>