[gtk+/wip/matthiasc/help-overlay] Add documentation for new application window API

[Matthias Clasen <matthiasc src gnome org>]

commit 62a57ef4e06123e5e5dee2212adbd3a2864f6b5b
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Oct 21 06:39:09 2015 -0400

    Add documentation for new application window API

 docs/reference/gtk/gtk3-sections.txt |    2 ++
 gtk/gtkapplication.c                 |   10 ++++++++--
 gtk/gtkapplicationwindow.c           |   22 ++++++++++++++++++++++
 3 files changed, 32 insertions(+), 2 deletions(-)
---
diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index f4482e1..d6274d7 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -7545,6 +7545,8 @@ gtk_application_window_new
 gtk_application_window_set_show_menubar
 gtk_application_window_get_show_menubar
 gtk_application_window_get_id
+gtk_application_window_set_help_overlay
+gtk_application_window_get_help_overlay
 
 <SUBSECTION Standard>
 GTK_TYPE_APPLICATION_WINDOW
diff --git a/gtk/gtkapplication.c b/gtk/gtkapplication.c
index d3b2559..1ca772d 100644
--- a/gtk/gtkapplication.c
+++ b/gtk/gtkapplication.c
@@ -75,7 +75,7 @@
  * ## Automatic resources ## {#automatic-resources}
  *
  * #GtkApplication will automatically load menus from the #GtkBuilder
- * file located at "gtk/menus.ui", relative to the application's
+ * resource located at "gtk/menus.ui", relative to the application's
  * resource base path (see g_application_set_resource_base_path()).  The
  * menu with the ID "app-menu" is taken as the application's app menu
  * and the menu with the ID "menubar" is taken as the application's
@@ -83,7 +83,7 @@
  * and accessed via gtk_application_get_menu_by_id() which allows for
  * dynamic population of a part of the menu structure.
  *
- * If the files "gtk/menus-appmenu.ui" or "gtk/menus-traditional.ui" are
+ * If the resources "gtk/menus-appmenu.ui" or "gtk/menus-traditional.ui" are
  * present then these files will be used in preference, depending on the
  * value of gtk_application_prefers_app_menu().
  *
@@ -96,6 +96,12 @@
  * resources.  See gtk_icon_theme_add_resource_path() for more
  * information.
  *
+ * If there is a resource located at "gtk/help-overlay.ui" which is
+ * defining a #GtkShortcutsWindow with ID "help_overlay" then GtkApplication
+ * will associate an instance of this shortcuts window with each
+ * #GtkApplicationWindow and set up accelerators Control-F1 and Control-?
+ * to open it.
+ *
  * ## A simple application ## {#gtkapplication}
  *
  * [A simple example](https://git.gnome.org/browse/gtk+/tree/examples/bp/bloatpad.c)
diff --git a/gtk/gtkapplicationwindow.c b/gtk/gtkapplicationwindow.c
index 4444335..9b7bbb7 100644
--- a/gtk/gtkapplicationwindow.c
+++ b/gtk/gtkapplicationwindow.c
@@ -973,6 +973,17 @@ show_help_overlay (GSimpleAction *action,
     gtk_widget_show (GTK_WIDGET (window->priv->help_overlay));
 }
 
+/**
+ * gtk_application_window_set_help_overlay:
+ * @window: a #GtkApplicationWindow
+ * @help_overlay: a #GtkShortcutsWindow
+ *
+ * Associates a shortcuts window with the application window, and
+ * sets up a action with the name win.show-help-overay to present
+ * it.
+ *
+ * Since: 3.20
+ */
 void
 gtk_application_window_set_help_overlay (GtkApplicationWindow *window,
                                          GtkShortcutsWindow   *help_overlay)
@@ -1004,6 +1015,17 @@ gtk_application_window_set_help_overlay (GtkApplicationWindow *window,
     }
 }
 
+/**
+ * gtk_application_window_get_help_overlay:
+ * @window: a #GtkApplicationWindow
+ *
+ * Gets the #GtkShortcutsWindow that has been set up with
+ * a prior call to gtk_application_window_set_help_overlay().
+ *
+ * Returns: the help overlay associated with @window, or %NULL
+ *
+ * Since: 3.20
+ */
 GtkShortcutsWindow *
 gtk_application_window_get_help_overlay (GtkApplicationWindow *window)
 {