[clutter/wip/layout-children: 28/29] docs: Clean up the documentation for the allocate() methods

[Emmanuele Bassi <ebassi src gnome org>]

commit e72a7235658bc4fae66b0b94a9f88f3547b514a1
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Wed Nov 28 09:47:44 2012 +0000

    docs: Clean up the documentation for the allocate() methods
    
    The wording could be better, especially on the side effects and the
    honoured state.

 clutter/clutter-actor.c |   26 +++++++++++++++++++-------
 1 files changed, 19 insertions(+), 7 deletions(-)
---
diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 36552bb..1495097 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -9631,9 +9631,18 @@ clutter_actor_allocate_internal (ClutterActor           *self,
  * @box: new allocation of the actor, in parent-relative coordinates
  * @flags: flags that control the allocation
  *
- * Called by the parent of an actor to assign the actor its size.
- * Should never be called by applications (except when implementing
- * a container or layout manager).
+ * Assigns the size of a #ClutterActor from the given @box.
+ *
+ * This function should only be called on the children of an actor when
+ * overriding the #ClutterActorClass.allocate() virtual function.
+ *
+ * This function will adjust the stored allocation to take into account
+ * the alignment flags set in the #ClutterActor:x-align and
+ * #ClutterActor:y-align properties, if the #ClutterActor:x-expand and
+ * the #ClutterActor:y-expand properties are set to %TRUE.
+ *
+ * This function will respect the easing state of the #ClutterActor and
+ * interpolate between the current allocation and the new one.
  *
  * Actors can know from their allocation box whether they have moved
  * with respect to their parent actor. The @flags parameter describes
@@ -15082,11 +15091,11 @@ clutter_actor_allocate_available_size (ClutterActor           *self,
  * by fixed layout managers (like #ClutterGroup or so called
  * 'composite actors') inside the ClutterActor::allocate
  * implementation to give each child exactly how much space it
- * requires.
+ * requires, regardless of the size of the parent.
  *
  * This function is not meant to be used by applications. It is also
  * not meant to be used outside the implementation of the
- * ClutterActor::allocate virtual function.
+ * #ClutterActorClass.allocate virtual function.
  *
  * Since: 0.8
  */
@@ -15150,8 +15159,11 @@ clutter_actor_allocate_preferred_size (ClutterActor           *self,
  * This function takes into consideration the geometry request specified by
  * the #ClutterActor:request-mode property, and the text direction.
  *
- * This function is useful for fluid layout managers, like #ClutterBinLayout
- * or #ClutterTableLayout
+ * This function is useful for fluid layout managers using legacy alignment
+ * flags. Newly written layout managers should use the #ClutterActor:x-align
+ * and #ClutterActor:y-align properties, instead, and just call
+ * clutter_actor_allocate() inside their #ClutterActorClass.allocate()
+ * implementation.
  *
  * Since: 1.4
  */