[clutter] docs: Clarify the Actor's iterator API behaviour

[Emmanuele Bassi <ebassi src gnome org>]

commit 673961f40cb69ad28806dfe763d74bac3662a8ad
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 7f4928b..a77b41f 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -15496,7 +15496,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
  *
@@ -15517,7 +15518,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
  *
@@ -15537,7 +15540,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
  *
@@ -15557,7 +15562,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
  *