[docs] More information on animation queueing

Queuing an animation on an actor cannot be done from within the
::completed signal handler, because we guarantee that the Animation
instance is valid and attached to the actor it animates for the
whole duration of the signal emission chain.

In order to queue animations you have to install an idle handler
on the main loop, and call clutter_actor_animate() inside it.

The documentation should be more clear about this caveat in the
memory management of ClutterAnimations created by the animate()
family of functions.

clutter/clutter-animation.c

@@ -362,6 +362,9 @@ clutter_animation_class_init (ClutterAnimationClass *klass)
    * The ::completed signal is emitted once the animation has
    * been completed.
    *
+   * The @animation instance is guaranteed to be valid for the entire
+   * duration of the signal emission chain.
+   *
    * Since: 1.0
    */
   animation_signals[COMPLETED] =
@@ -1657,6 +1660,46 @@ clutter_actor_animate_with_timeline (ClutterActor    *actor,
  * alive across multiple cycles, you also have to add a reference each
  * time the #ClutterAnimation::completed signal is emitted.</note>
  *
+ * Since the created #ClutterAnimation instance attached to @actor
+ * is guaranteed to be valid throughout the #ClutterAnimation::completed
+ * signal emission chain, you will not be able to create a new animation
+ * using clutter_actor_animate() on the same @actor from within the
+ * #ClutterAnimation::completed signal handler. Instead, you should use
+ * clutter_threads_add_idle() to install an idle handler and call
+ * clutter_actor_animate() in the handler, for instance:
+ *
+ * |[
+ *   static gboolean
+ *   queue_animation (gpointer data)
+ *   {
+ *     ClutterActor *actor = data;
+ *
+ *     clutter_actor_animate (actor, 250, CLUTTER_EASE_IN_CUBIC,
+ *                            "width", 200,
+ *                            "height", 200,
+ *                            NULL);
+ *
+ *     return FALSE;
+ *   }
+ *
+ *   static void
+ *   on_animation_completed (ClutterAnimation *animation)
+ *   {
+ *     clutter_threads_add_idle (queue_animation,
+ *                               clutter_animation_get_object (animation));
+ *   }
+ *
+ *     ...
+ *     animation = clutter_actor_animate (actor, 250, CLUTTER_EASE_IN_CUBIC,
+ *                                        "x", 100,
+ *                                        "y", 100,
+ *                                        NULL);
+ *     g_signal_connect (animation, "completed",
+ *                       G_CALLBACK (on_animation_completed),
+ *                       NULL);
+ *     ...
+ * ]|
+ *
  * Return value: (transfer none): a #ClutterAnimation object. The object is
  *   owned by the #ClutterActor and should not be unreferenced with
  *   g_object_unref()