[gtk/gtk-3-24] container: Document that removal from foreach is permissible

[Daniel Boles <dboles src gnome org>]

commit 356f1f59aeba13192227da96986a7dc31614c06a
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 88f1fc415e..33578ab65a 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -2456,6 +2456,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 70a429bcf7..9658b4a4f4 100644
--- a/gtk/gtkcontainer.h
+++ b/gtk/gtkcontainer.h
@@ -60,7 +60,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.
  * @composite_name: Gets a widget’s composite name. Deprecated: 3.10.