[gtk+/wip/gmenu] Some initial docs

[Matthias Clasen <matthiasc src gnome org>]

commit 2bcc8bb0660ed60df95884054af3e40ea85983a7
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Nov 30 19:14:48 2011 -0500

    Some initial docs

 gtk/gtkapplicationwindow.c |   42 +++++++++++++++++++++++++++++++-----------
 gtk/gtksettings.c          |    4 +++-
 2 files changed, 34 insertions(+), 12 deletions(-)
---
diff --git a/gtk/gtkapplicationwindow.c b/gtk/gtkapplicationwindow.c
index 90a75ce..cf7a29a 100644
--- a/gtk/gtkapplicationwindow.c
+++ b/gtk/gtkapplicationwindow.c
@@ -28,6 +28,28 @@
 #include "gtkmenubar.h"
 #include "gactionmuxer.h"
 
+/**
+ * SECTION:gtkapplicationwindow
+ * @title: GtkApplicationWindow
+ * @short_description: GtkWindow subclass with GtkApplication support
+ *
+ * GtkApplicationWindow is a #GtkWindow subclass that offers some extra
+ * functionality for better integration with #GtkApplication features.
+ * It implements the #GActionGroup and #GActionMap interfaces, to let
+ * you add window-specific actions that will be exported by the associated
+ * #GtkApplication, together with its application-wide actions.
+ * Window-specific actions are prefixed with the "win." prefix and
+ * application-wide actions are prefixed with the "app." prefix.
+ * Actions must be addressed with the prefixed name when referring
+ * to them from a #GMenuModel.
+ *
+ * If the desktop environment does not display the application menu
+ * as part of the desktop shell, then #GApplicationWindow will
+ * automatically show the menu as part of a menubar. This behaviour
+ * can be overridden with the #GtkApplicationWindow:show-app-menu
+ * property.
+ */
+
 struct _GtkApplicationWindowPrivate
 {
   GSimpleActionGroup *actions;
@@ -828,27 +850,25 @@ items_changed (GMenuModel *model,
 
 /**
  * gtk_application_window_get_app_menu:
- * @application: a #GtkApplication
+ * @window: a #GtkApplicationWindow
  *
  * Populates a menu widget from a menu model that is
- * associated with @application. See g_application_set_menu().
- * The menu items will be connected to action of @application,
- * as indicated by the menu model. The menus contents will be
- * updated automatically in response to menu model changes.
+ * associated with @window. See g_application_set_menu().
+ * The menu items will be connected to actions of @window or
+ * its associated #GtkApplication, as indicated by the menu model.
+ * The menus contents will be updated automatically in response
+ * to menu model changes.
  *
  * It is the callers responsibility to add the menu at a
  * suitable place in the widget hierarchy.
  *
- * This function returns %NULL if @application has no associated
- * menu model. It also returns %NULL if the menu model is
- * represented outside the application, e.g. by an application
- * menu in the desktop shell.
+ * This function returns %NULL if @window has no associated
+ * menu model.
  *
  * @menu may be a #GtkMenu or a #GtkMenuBar.
  *
  * Returns: A #GtkMenu that has been populated from the
- *     #GMenuModel that is associated with @application,
- *     or %NULL
+ *     #GMenuModel that is associated with @window, or %NULL
  */
 GtkWidget *
 gtk_application_window_get_app_menu (GtkApplicationWindow *window)
diff --git a/gtk/gtksettings.c b/gtk/gtksettings.c
index 510e591..a516748 100644
--- a/gtk/gtksettings.c
+++ b/gtk/gtksettings.c
@@ -1323,7 +1323,9 @@ gtk_settings_class_init (GtkSettingsClass *class)
   result = settings_install_property_parser (class,
                                              g_param_spec_boolean ("gtk-shell-shows-app-menu",
                                                                    P_("Desktop shell shows app menu"),
-                                                                   P_("Set to true if the desktop environment is displaying the app menu, FALSE if the app should display it itself."),
+                                                                   P_("Set to TRUE if the desktop environment "
+                                                                      "is displaying the app menu, FALSE if "
+                                                                      "the app should display it itself."),
                                                                    FALSE, GTK_PARAM_READWRITE),
                                              NULL);
   g_assert (result == PROP_SHELL_SHOWS_APP_MENU);