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.