[gtk+] container: Clarify the forall/foreach documentation

[Matthias Clasen <matthiasc src gnome org>]

commit 8ba996a6dbfb8a028b74ef43125c472ae6293c75
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Jan 23 01:51:48 2016 -0500

    container: Clarify the forall/foreach documentation
    
    Try to make the difference between these two functions
    clearer.

 gtk/gtkcontainer.c |   27 +++++++++++++++++----------
 1 files changed, 17 insertions(+), 10 deletions(-)
---
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 2f4cf2a..69ffbd7 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -2387,12 +2387,14 @@ gtk_container_class_handle_border_width (GtkContainerClass *klass)
  * @callback: (scope call) (closure callback_data): a callback
  * @callback_data: callback user data
  *
- * Invokes @callback on each child of @container, including children
- * that are considered “internal” (implementation details of the
- * container). “Internal” children generally weren’t added by the user
- * of the container, but were added by the container implementation
- * itself.  Most applications should use gtk_container_foreach(),
- * rather than gtk_container_forall().
+ * Invokes @callback on each direct child of @container, including
+ * children that are considered “internal” (implementation details
+ * of the container). “Internal” children generally weren’t added
+ * by the user of the container, but were added by the container
+ * implementation itself.
+ *
+ * Most applications should use gtk_container_foreach(), rather
+ * than gtk_container_forall().
  **/
 void
 gtk_container_forall (GtkContainer *container,
@@ -2416,10 +2418,15 @@ gtk_container_forall (GtkContainer *container,
  * @callback: (scope call):  a callback
  * @callback_data: callback user data
  *
- * Invokes @callback on each non-internal child of @container. See
- * gtk_container_forall() for details on what constitutes an
- * “internal” child.  Most applications should use
- * gtk_container_foreach(), rather than gtk_container_forall().
+ * Invokes @callback on each non-internal child of @container.
+ * See gtk_container_forall() for details on what constitutes
+ * an “internal” child. For all practical purposes, this function
+ * should iterate over precisely those child widgets that were
+ * added to the container by the application with explicit add()
+ * calls.
+ *
+ * Most applications should use gtk_container_foreach(),
+ * rather than gtk_container_forall().
  **/
 void
 gtk_container_foreach (GtkContainer *container,