[gtk+] container: clarify the docs

[Stefan Kost <stefkost src gnome org>]

commit 267a2156d829b9bb3a8b72ea511fecaa2e54ffe9
Author: Stefan Kost <ensonic users sf net>
Date:   Fri Aug 20 13:55:41 2010 +0300

    container: clarify the docs
    
    Hightlight more that focus_child is a container internal thing and suggest
    what application developers most likely were looking for instead.

 gtk/gtkcontainer.c |   11 ++++++++---
 1 files changed, 8 insertions(+), 3 deletions(-)
---
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 0a1f705..839ae43 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -1587,6 +1587,9 @@ gtk_container_foreach (GtkContainer *container,
  * This function emits the GtkContainer::set_focus_child signal of
  * @container. Implementations of #GtkContainer can override the
  * default behaviour by overriding the class closure of this signal.
+ *
+ * This is function is mostly meant to be used by widgets. Applications can use
+ * gtk_widget_grab_focus() to manualy set the focus to a specific widget.
  */
 void
 gtk_container_set_focus_child (GtkContainer *container,
@@ -1603,10 +1606,12 @@ gtk_container_set_focus_child (GtkContainer *container,
  * gtk_container_get_focus_child:
  * @container: a #GtkContainer
  *
- * Returns the current focus child widget inside @container.
+ * Returns the current focus child widget inside @container. This is not the
+ * currently focused widget. That can be obtained by calling
+ * gtk_window_get_focus().
  *
- * Returns: The child widget which has the focus
- *          inside @container, or %NULL if none is set.
+ * Returns: The child widget which will recieve the focus inside @container when
+ *          the @conatiner is focussed, or %NULL if none is set.
  *
  * Since: 2.14
  **/