From 68da998c9bc81fa7f2f163032e19640aae9100e7 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@linux.intel.com>
Date: Fri, 17 Sep 2010 14:54:31 +0100
Subject: [PATCH] docs: Add sub-classing notes on ActorMeta and Constraint

---
 clutter/clutter-actor-meta.c |  8 ++++++--
 clutter/clutter-constraint.c | 26 ++++++++++++++++++++++++++
 2 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/clutter/clutter-actor-meta.c b/clutter/clutter-actor-meta.c
index c860e3115..c28e0ef26 100644
--- a/clutter/clutter-actor-meta.c
+++ b/clutter/clutter-actor-meta.c
@@ -5,10 +5,14 @@
  * @See_Also: #ClutterAction, #ClutterConstraint
  *
  * #ClutterActorMeta is an abstract class providing a common API for
- * modifiers of #ClutterActor
+ * modifiers of #ClutterActor behaviour, appearance or layout.
  *
  * A #ClutterActorMeta can only be owned by a single #ClutterActor at
- * any time
+ * any time.
+ *
+ * Every sub-class of #ClutterActorMeta should check if the
+ * #ClutterActorMeta:enabled property is set to %TRUE before applying
+ * any kind of modification.
  *
  * #ClutterActorMeta is available since Clutter 1.4
  */
diff --git a/clutter/clutter-constraint.c b/clutter/clutter-constraint.c
index 6e0bf2865..829b079ea 100644
--- a/clutter/clutter-constraint.c
+++ b/clutter/clutter-constraint.c
@@ -13,6 +13,32 @@
  * allocation of the actor to which they are applied by overriding the
  * <function>update_allocation()</function> virtual function.
  *
+ * <refsect2 id="ClutterConstraint-implementation">
+ *   <title>Implemting a ClutterConstraint</title>
+ *   <para>Creating a sub-class of #ClutterConstraint requires the
+ *   implementation of the <function>update_allocation()</function>
+ *   virtual function.</para>
+ *   <para>The <function>update_allocation()</function> virtual function
+ *   is called during the allocation sequence of a #ClutterActor, and
+ *   allows any #ClutterConstraint attached to that actor to modify the
+ *   allocation before it is passed to the <function>allocate()</function>
+ *   implementation.</para>
+ *   <para>The #ClutterActorBox passed to the
+ *   <function>update_allocation()</function> implementation contains the
+ *   original allocation of the #ClutterActor, plus the eventual modifications
+ *   applied by the other #ClutterConstraint<!-- -->s.</para>
+ *   <note><para>Constraints are queried in the same order as they were
+ *   applied using clutter_actor_add_constraint() or
+ *   clutter_actor_add_constraint_with_name().</para></note>
+ *   <para>It is not necessary for a #ClutterConstraint sub-class to chain
+ *   up to the parent's implementation.</para>
+ *   <para>If a #ClutterConstraint is parametrized - i.e. if it contains
+ *   properties that affect the way the constraint is implemented - it should
+ *   call clutter_actor_queue_relayout() on the actor to which it is attached
+ *   to whenever any parameter is changed. The actor to which it is attached
+ *   can be recovered at any point using clutter_actor_meta_get_actor().</para>
+ * </refsect2>
+ *
  * #ClutterConstraint is available since Clutter 1.4
  */