[clutter] docs: Clarify actor map and unmap methods

[Emmanuele Bassi <ebassi src gnome org>]

commit 9872d7eb1b31112f3f72855ef00334f39cdb949f
Author: Emmanuele Bassi <ebassi linux intel com>
Date:   Thu Feb 2 11:18:00 2012 +0000

    docs: Clarify actor map and unmap methods
    
    ClutterActor stopped requiring to override the map and unmap virtual
    functions some time ago.
    
    Now that ClutterActor implements the Container interface, overriding map
    and unmap to control the MAPPED state of the children is pretty much
    going to be a source of bugs and misunderstandings.
    
    Plus, the ordering of the unmap, destroy, dispose, and finalize calls
    should be be documented properly.
    
    The documentation should clarify all that.

 clutter/clutter-actor.c |   26 ++++++++++++++------------
 1 files changed, 14 insertions(+), 12 deletions(-)
---
diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 090a2a1..7786b0d 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -1135,11 +1135,9 @@ clutter_actor_real_map (ClutterActor *self)
  * and realizes its children if they are visible. Does nothing if the
  * actor is not visible.
  *
- * Calling this is allowed in only one case: you are implementing the
- * #ClutterActor <function>map()</function> virtual function in an actor
- * and you need to map the children of that actor. It is not necessary
- * to call this if you implement #ClutterContainer because the default
- * implementation will automatically map children of containers.
+ * Calling this function is strongly disencouraged: the default
+ * implementation of #ClutterActorClass.map() will map all the children
+ * of an actor when mapping its parent.
  *
  * When overriding map, it is mandatory to chain up to the parent
  * implementation.
@@ -1218,14 +1216,18 @@ clutter_actor_real_unmap (ClutterActor *self)
  * Unsets the %CLUTTER_ACTOR_MAPPED flag on the actor and possibly
  * unmaps its children if they were mapped.
  *
- * Calling this is allowed in only one case: you are implementing the
- * #ClutterActor <function>unmap()</function> virtual function in an actor
- * and you need to unmap the children of that actor. It is not necessary
- * to call this if you implement #ClutterContainer because the default
- * implementation will automatically unmap children of containers.
+ * Calling this function is not encouraged: the default #ClutterActor
+ * implementation of #ClutterActorClass.unmap() will also unmap any
+ * eventual children by default when their parent is unmapped.
  *
- * When overriding unmap, it is mandatory to chain up to the parent
- * implementation.
+ * When overriding #ClutterActorClass.unmap(), it is mandatory to
+ * chain up to the parent implementation.
+ *
+ * <note>It is important to note that the implementation of the
+ * #ClutterActorClass.unmap() virtual function may be called after
+ * the #ClutterActorClass.destroy() or the #GObjectClass.dispose()
+ * implementation, but it is guaranteed to be called before the
+ * #GObjectClass.finalize() implementation.</note>
  *
  * Since: 1.0
  */