[gtk+] Expand builder menu documentation

[Matthias Clasen <matthiasc src gnome org>]

commit ce3ebaf6f9327834e41126d36c1ecc01a142c70b
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Jul 29 23:17:43 2015 -0400

    Expand builder menu documentation
    
    List the supported attributes.

 gtk/gtkapplicationwindow.c |   30 ++++++++++++++++++++++++------
 1 files changed, 24 insertions(+), 6 deletions(-)
---
diff --git a/gtk/gtkapplicationwindow.c b/gtk/gtkapplicationwindow.c
index 5007997..8602a98 100644
--- a/gtk/gtkapplicationwindow.c
+++ b/gtk/gtkapplicationwindow.c
@@ -70,13 +70,10 @@
  *
  * If the desktop environment does not display the menubar, then
  * #GtkApplicationWindow will automatically show a #GtkMenuBar for it.
- * (see the #GtkApplication docs for some screenshots of how this
- * looks on different platforms).
  * This behaviour can be overridden with the #GtkApplicationWindow:show-menubar
  * property. If the desktop environment does not display the application
- * menu, then it will automatically be included in the menubar. It can
- * also be shown as part of client-side window decorations, e.g. by
- * using gtk_header_bar_set_show_close_button().
+ * menu, then it will automatically be included in the menubar or in the
+ * windows client-side decorations.
  *
  * ## A GtkApplicationWindow with a menubar
  *
@@ -112,7 +109,9 @@
  * of a toplevel `<menu>` element, which contains one or more `<item>`
  * elements. Each `<item>` element contains `<attribute>` and `<link>`
  * elements with a mandatory name attribute. `<link>` elements have the
- * same content model as `<menu>`.
+ * same content model as `<menu>`. Instead of `<link name="submenu>` or
+ * `<link name="section">`, you can use `<submenu>` or `<section>`
+ * elements.
  *
  * Attribute values can be translated using gettext, like other #GtkBuilder
  * content. `<attribute>` elements can be marked for translation with a
@@ -120,6 +119,25 @@
  * context and translator comments, using the context and comments attributes.
  * To make use of this, the #GtkBuilder must have been given the gettext
  * domain to use.
+ *
+ * The following attributes are used when constructing menu items:
+ * - "label": a user-visible string to display
+ * - "action": the prefixed name of the action to trigger
+ * - "target": the parameter to use when activating the action
+ * - "icon" and "verb-icon": names of icons that may be displayed
+ * - "submenu-action": name of an action that may be used to determine
+ *      if a submenu can be opened
+ * - "hidden-when": a string used to determine when the item will be hidden.
+ *      Possible values include "action-disabled", "action-missing", "macos-menubar".
+ *
+ * The following attributes are used when constructing sections:
+ * - "label": a user-visible string to use as section heading
+ * - "display-hint": a string used to determine special formatting for the section.
+ *     Possible values include "horizontal-buttons".
+ *
+ * The following attributes are used when constructing submenus:
+ * - "label": a user-visible string to display
+ * - "icon": icon name to display
  */
 
 typedef GSimpleActionGroupClass GtkApplicationWindowActionsClass;