Some initial docs

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().
+ * associated with @window. See g_application_set_menu().
- * The menu items will be connected to action of @application,
+ * The menu items will be connected to actions of @window or
- * as indicated by the menu model. The menus contents will be
+ * its associated #GtkApplication, as indicated by the menu model.
- * updated automatically in response to menu model changes.
+ * 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
+ * This function returns %NULL if @window has no associated
- * menu model. It also returns %NULL if the menu model is
+ * menu model.
- * represented outside the application, e.g. by an application
- * menu in the desktop shell.
  *
  * @menu may be a #GtkMenu or a #GtkMenuBar.
  *
  * Returns: A #GtkMenu that has been populated from the
- *     #GMenuModel that is associated with @application,
+ *     #GMenuModel that is associated with @window, or %NULL
- *     or %NULL
  */
 GtkWidget *
 gtk_application_window_get_app_menu (GtkApplicationWindow *window)

gtk/gtksettings.c

@@ -1327,7 +1327,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);