[gtk: 1/2] container: Document that removal from foreach is permissible

[Timm Bäder <baedert src gnome org>]

commit 8c9c3e4426269c34a778b9aa077e3649014916c2
Author: Benjamin Berg <bberg redhat com>
Date:   Mon Nov 19 13:48:36 2018 +0100

    container: Document that removal from foreach is permissible
    
    It is permissable to remove a widget using gtk_container_remove from the
    gtk_container_foreach callback handler. Document this fact to make it
    more discoverable.
    
    Fixes #1461

 gtk/gtkcontainer.c | 2 ++
 gtk/gtkcontainer.h | 3 ++-
 2 files changed, 4 insertions(+), 1 deletion(-)
---
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 7bb9524658..20f75f4ca7 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -1574,6 +1574,8 @@ gtk_container_forall (GtkContainer *container,
  * added to the container by the application with explicit add()
  * calls.
  *
+ * It is permissible to remove the child from the @callback handler.
+ *
  * Most applications should use gtk_container_foreach(),
  * rather than gtk_container_forall().
  **/
diff --git a/gtk/gtkcontainer.h b/gtk/gtkcontainer.h
index 37d49805cc..8f07f97408 100644
--- a/gtk/gtkcontainer.h
+++ b/gtk/gtkcontainer.h
@@ -57,7 +57,8 @@ struct _GtkContainer
  * @add: Signal emitted when a widget is added to container.
  * @remove: Signal emitted when a widget is removed from container.
  * @check_resize: Signal emitted when a size recalculation is needed.
- * @forall: Invokes callback on each child of container.
+ * @forall: Invokes callback on each child of container. The callback handler
+ *    may remove the child.
  * @set_focus_child: Sets the focused child of container.
  * @child_type: Returns the type of the children supported by the container.
  * @set_child_property: Set a property on a child of container.