diff --git a/ChangeLog b/ChangeLog
index 7ee1259ab..3e88e2ea2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2008-02-07  Emmanuele Bassi  <ebassi@openedhand.com>
+
+	* clutter/clutter-actor.c: Add a note on clutter_actor_set_size()
+	reguarding groups.
+
+	* clutter/clutter-group.c: Clarify group sizing.
+
 2008-02-07  Øyvind Kolås  <pippin@o-hand.com>
 
 	* tests/test-shader.c: (button_release_cb): added simplified
diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 2a0d14f47..2dcad53e6 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -2198,8 +2198,7 @@ clutter_actor_get_coords (ClutterActor *self,
  * @x: New left position of actor in pixels.
  * @y: New top position of actor in pixels.
  *
- * Sets the actors position in pixels relative to any
- * parent actor.
+ * Sets the actors position in pixels relative to any parent actor.
  */
 void
 clutter_actor_set_position (ClutterActor *self,
@@ -2354,8 +2353,15 @@ clutter_actor_set_size_internalu (ClutterActor *self,
  * @width: New width of actor in pixels, or -1
  * @height: New height of actor in pixels, or -1
  *
- * Sets the actors size in pixels. If @width and/or @height are -1 the
- * actor will assume the same size of its bounding box.
+ * Sets the actors size in pixels.
+ *
+ * If @width and/or @height are -1 the actor will assume the same size
+ * of its bounding box.
+ *
+ * <note>This function is a "request" to the #ClutterActor. Depending
+ * on the actual implementation, calling clutter_actor_set_size() might
+ * not produce visible results. Calling this function on a #ClutterGroup,
+ * for instance, will not resize the group.</note>
  */
 void
 clutter_actor_set_size (ClutterActor *self,
diff --git a/clutter/clutter-group.c b/clutter/clutter-group.c
index 503a39178..75ee9919f 100644
--- a/clutter/clutter-group.c
+++ b/clutter/clutter-group.c
@@ -34,7 +34,9 @@
  *
  * A #ClutterGroup's size is defined by the size and position of it
  * it children. Resize requests via parent #ClutterActor API will be
- * ignored.
+ * ignored, i.e. calling clutter_actor_set_size() on a #ClutterGroup
+ * will not resize the group nor its children. If you want to resize
+ * a group, call clutter_actor_set_scale().
  */
 
 #ifdef HAVE_CONFIG_H