docs: Clarify Group's sizing semantics

The documentation for ClutterGroup behaviour when setting an explicit
size is not accurate - or, actually, it was accurate by the time
ClutterGroup was first written but has been neglected in the following
release cycles.

To avoid confusion for new users of Clutter the documentation should be
slightly expanded, mentioning the exact semantics of ClutterGroup with
regards to: preferred size, explicitly set size and how to constrain the
visible area of a ClutterGroup to an explicitly set size.

Based on a patch by: Neil Roberts <neil@linux.intel.com>

diff --git a/clutter/clutter-group.c b/clutter/clutter-group.c
index 0599316..960b82f 100644 (file)
--- a/clutter/clutter-group.c
+++ b/clutter/clutter-group.c
@@ -25,15 +25,23 @@
 
 /**
  * SECTION:clutter-group
- * @short_description: Actor class containing multiple children.
- * actors.
+ * @short_description: A fixed layout container
  *
  * A #ClutterGroup is an Actor which contains multiple child actors positioned
  * relative to the #ClutterGroup position. Other operations such as scaling,
  * rotating and clipping of the group will apply to the child actors.
  *
- * A #ClutterGroup's size is defined by the size and position of its children.
- * Resize requests via the #ClutterActor API will be ignored.
+ * A #ClutterGroup's size is defined by the size and position of its children;
+ * it will be the smallest non-negative size that covers the right and bottom
+ * edges of all of its children.
+ *
+ * Setting the size on a Group using #ClutterActor methods like
+ * clutter_actor_set_size() will override the natural size of the Group,
+ * however this will not affect the size of the children and they may still
+ * be painted outside of the allocation of the group. One way to constrain
+ * the visible area of a #ClutterGroup to a specified allocation is to
+ * explicitly set the size of the #ClutterGroup and then use the
+ * #ClutterActor:clip-to-allocation property.
  */
 
 #ifdef HAVE_CONFIG_H