diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 2cde2b036..f2ced6079 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -226,11 +226,12 @@
* will automatically transition an actor's property change between the
* current state and the desired one without manual intervention, if the
* property is defined to be animatable in its documentation.
- * By default, in the 1.0 API series, the transition happens with
- * a duration of zero milliseconds, and the implicit animation is an
- * opt in feature to retain backwards compatibility. In order to enable
- * implicit animations, it is necessary to change the easing state of
- * an actor by using clutter_actor_save_easing_state():
+ * By default, in the 1.0 API series, the transition happens
+ * with a duration of zero milliseconds, and the implicit animation is an
+ * opt in feature to retain backwards compatibility.
+ * Implicit animations depend on the current easing state; in order
+ * to use the default easing state for an actor you should call the
+ * clutter_actor_save_easing_state() function:
*
* /* assume that the actor is currently positioned at (100, 100) */
* clutter_actor_save_easing_state (actor);
@@ -259,6 +260,8 @@
* and a default easing mode of %CLUTTER_EASE_OUT_CUBIC, unless you call
* clutter_actor_set_easing_mode() and clutter_actor_set_easing_duration()
* after changing the easing state of the actor.
+ * Changing the easing state will affect all the following property
+ * transitions, but will not affect existing transitions.
* It is important to note that if you modify the state on an
* animatable property while a transition is in flight, the transition's
* final value will be updated, as well as its duration and progress
@@ -266,17 +269,20 @@
* example:
*
* clutter_actor_save_easing_state (actor);
+ * clutter_actor_set_easing_duration (actor, 1000);
* clutter_actor_set_x (actor, 200);
* clutter_actor_restore_easing_state (actor);
*
* clutter_actor_save_easing_state (actor);
+ * clutter_actor_set_easing_duration (actor, 500);
* clutter_actor_set_x (actor, 100);
* clutter_actor_restore_easing_state (actor);
*
* the first call to clutter_actor_set_x() will begin a transition
- * of the #ClutterActor:x property to the value of 200; the second call
- * to clutter_actor_set_x() will change the transition's final value to
- * 100.
+ * of the #ClutterActor:x property from the current value to the value of
+ * 200 over a duration of one second; the second call to clutter_actor_set_x()
+ * will change the transition's final value to 100 and the duration to 500
+ * milliseconds.
* It is possible to retrieve the #ClutterTransition used by the
* animatable properties by using clutter_actor_get_transition() and using
* the property name as the transition name.
@@ -303,7 +309,10 @@
* of an actor between fully opaque and fully transparent, and back, over
* a span of 3 seconds. The animation does not begin until it is added to
* the actor.
- * The explicit animation API applies to all #GObject properties.
+ * The explicit animation API applies to all #GObject properties,
+ * as well as the custom properties defined through the #ClutterAnimatable
+ * interface, regardless of whether they are defined as implicitly
+ * animatable or not.
* The explicit animation API should also be used when using custom
* animatable properties for #ClutterAction, #ClutterConstraint, and
* #ClutterEffect instances associated to an actor; see the section on
@@ -457,7 +466,6 @@
* ClutterActor *rect)
* {
* ClutterTransition *transition;
- * ClutterInterval *interval;
*
* /* the offset that we want to apply; this will make the actor
* * slide in from behind the origin and rest at the right of
@@ -482,8 +490,8 @@
* clutter_timeline_set_duration (CLUTTER_TIMELINE (transition), 500);
*
* /* create the interval with the initial and final values */
- * interval = clutter_interval_new (G_TYPE_FLOAT, 0, new_offset);
- * clutter_transition_set_interval (transition, interval);
+ * clutter_transition_set_from (transition, G_TYPE_FLOAT, 0.f);
+ * clutter_transition_set_to (transition, G_TYPE_FLOAT, new_offset);
*
* /* add the transition to the actor; this causes the animation
* * to start. the name "offsetAnimation" can be used to retrieve