[clutter/wip/apocalypses/apocalypse-1: 64/92] docs: Clarify the Actor's iterator API behaviour

[Emmanuele Bassi <ebassi src gnome org>]

commit 272061aa4d5b8a613cdf950b88cc1f4a4bae5e84
Author: Emmanuele Bassi <ebassi linux intel com>
Date:   Mon Dec 19 17:34:22 2011 +0000

    docs: Clarify the Actor's iterator API behaviour
    
    It should be noted in the documentation that it is not safe to operate
    on the list of children of an Actor while iterating over it.

 clutter/clutter-actor.c |   15 +++++++++++----
 1 files changed, 11 insertions(+), 4 deletions(-)
---
diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 3df1382..5ce9692 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -15503,7 +15503,8 @@ clutter_actor_get_background_color (ClutterActor *self,
  * of children of @self's parent.
  *
  * The returned pointer is only valid until the scene graph changes; it
- * is guaranteed to remain the same during the paint sequence.
+ * is not safe to modify the list of children of @self while iterating
+ * it.
  *
  * Return value: (transfer none): a pointer to a #ClutterActor, or %NULL
  *
@@ -15524,7 +15525,9 @@ clutter_actor_get_previous_sibling (ClutterActor *self)
  * Retrieves the sibling of @self that comes after it in the list
  * of children of @self's parent.
  *
- * The returned pointer is only valid until the scene graph changes.
+ * The returned pointer is only valid until the scene graph changes; it
+ * is not safe to modify the list of children of @self while iterating
+ * it.
  *
  * Return value: (transfer none): a pointer to a #ClutterActor, or %NULL
  *
@@ -15544,7 +15547,9 @@ clutter_actor_get_next_sibling (ClutterActor *self)
  *
  * Retrieves the first child of @self.
  *
- * The returned pointer is only valid until the scene graph changes.
+ * The returned pointer is only valid until the scene graph changes; it
+ * is not safe to modify the list of children of @self while iterating
+ * it.
  *
  * Return value: (transfer none): a pointer to a #ClutterActor, or %NULL
  *
@@ -15564,7 +15569,9 @@ clutter_actor_get_first_child (ClutterActor *self)
  *
  * Retrieves the last child of @self.
  *
- * The returned pointer is only valid until the scene graph changes.
+ * The returned pointer is only valid until the scene graph changes; it
+ * is not safe to modify the list of children of @self while iterating
+ * it.
  *
  * Return value: (transfer none): a pointer to a #ClutterActor, or %NULL
  *