[gtk/wip/matthiasc/focus2: 38/50] Expand docs

[Matthias Clasen <matthiasc src gnome org>]

commit 7e2aa0f3af37b5dbc4d2815bb2fe0f7253077a68
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Mar 4 20:15:39 2019 -0500

    Expand docs

 gtk/gtkwidget.c | 25 +++++++++++++------------
 gtk/gtkwidget.h |  5 ++++-
 2 files changed, 17 insertions(+), 13 deletions(-)
---
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index d7dff52e7a..9dc34ddc01 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -5298,16 +5298,11 @@ _gtk_widget_grab_notify (GtkWidget *widget,
  * gtk_widget_grab_focus:
  * @widget: a #GtkWidget
  *
- * Causes @widget to have the keyboard focus for the #GtkWindow it's
- * inside. @widget must be a focusable widget, such as a #GtkEntry;
- * something like #GtkFrame won’t work.
+ * Causes @widget (or one of its descendents) to have the keyboard focus
+ * for the #GtkWindow it's inside.
  *
- * More precisely, it must have the %GTK_CAN_FOCUS flag set. Use
- * gtk_widget_set_can_focus() to modify that flag.
- *
- * The widget also needs to be realized and mapped. This is indicated by the
- * related signals. Grabbing the focus immediately after creating the widget
- * will likely fail and cause critical warnings.
+ * @widget must be focusable, or have a ::grab_focus implementation that
+ * transfers the focus to a descendant of @widget that is focusable.
  **/
 void
 gtk_widget_grab_focus (GtkWidget *widget)
@@ -5463,9 +5458,15 @@ gtk_widget_real_keynav_failed (GtkWidget        *widget,
  * @widget: a #GtkWidget
  * @can_focus: whether or not @widget can own the input focus.
  *
- * Specifies whether @widget can own the input focus. See
- * gtk_widget_grab_focus() for actually setting the input focus on a
- * widget.
+ * Specifies whether @widget can own the input focus.
+ * 
+ * Note that having @can_focus be %TRUE is only one of the
+ * necessary conditions for being focusable. A widget must
+ * also be sensitive and not have a ancestor that is marked
+ * as not child-focusable in order to receive input focus.
+ *
+ * See gtk_widget_grab_focus() for actually setting the input
+ * focus on a widget.
  **/
 void
 gtk_widget_set_can_focus (GtkWidget *widget,
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index 28b34a97e4..9ae7348cea 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -185,7 +185,10 @@ struct _GtkWidget
  *   %FALSE, and just grabs the focus if @group_cycling is %TRUE.
  * @grab_focus: Causes @widget to have the keyboard focus for the
  *   #GtkWindow it’s inside.
- * @next_focus_child: Returns the next child that is a candidate for receiving focus
+ * @next_focus_child: Returns the next child that is a candidate for receiving focus.
+ *   Note that the returned child does not have to be focusable itself, it might just
+ *   contain focusable children. The default implementation returns all children, in
+ *   their logical order.
  * @move_focus: Signal emitted when a change of focus is requested
  * @keynav_failed: Signal emitted if keyboard navigation fails.
  * @drag_begin: Signal emitted on the drag source when a drag is