diff --git a/ChangeLog b/ChangeLog
index 854293cb8..1d9d5778a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2008-02-08  Emmanuele Bassi  <ebassi@openedhand.com>
+
+	* clutter/clutter-behaviour-path.c: Add a paragraph describing
+	the effects of different alpha functions on the path behaviour.
+
 2008-02-08  Emmanuele Bassi  <ebassi@openedhand.com>
 
 	* clutter/clutter-actor.c: Reference the newly added event-flow.png
diff --git a/clutter/clutter-behaviour-path.c b/clutter/clutter-behaviour-path.c
index 63099a59a..ff4aee8ca 100644
--- a/clutter/clutter-behaviour-path.c
+++ b/clutter/clutter-behaviour-path.c
@@ -45,6 +45,17 @@
  *   <graphic fileref="path-alpha-func.png" format="PNG"/>
  * </figure>
  *
+ * The actors position between the path's end points directly correlates
+ * to the #ClutterAlpha's current alpha value driving the behaviour. With
+ * the #ClutterAlpha's function set to %CLUTTER_ALPHA_RAMP_INC the actor
+ * will follow the path at a constant velocity, but when changing to
+ * %CLUTTER_ALPHA_SINE_INC the actor initially accelerates quickly before
+ * quickly decelerating.
+ *
+ * <note>If the alpha function is a periodic function, i.e. it returns to
+ * 0 after reaching %CLUTTER_ALPHA_MAX_ALPHA, then the actors will walk
+ * the path back to the starting #ClutterKnot.</note>
+ *
  * #ClutterBehaviourPath is available since Clutter 0.2
  */