[glib/wip/menus-rebase2] More docs

[Matthias Clasen <matthiasc src gnome org>]

commit 7be1e1010036c23913e910fd05dc675eb7fe8fbe
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Nov 24 23:42:29 2011 -0500

    More docs
    
    Explain boolean and radio items and how they are modeled
    by stateful actions.

 gio/gmenu.c      |    5 ++++-
 gio/gmenumodel.c |   25 +++++++++++++++++++++----
 2 files changed, 25 insertions(+), 5 deletions(-)
---
diff --git a/gio/gmenu.c b/gio/gmenu.c
index f51e9e0..151162f 100644
--- a/gio/gmenu.c
+++ b/gio/gmenu.c
@@ -35,7 +35,10 @@
  * You populate a #GMenu by adding #GMenuItem instances to it.
  *
  * There are some convenience functions to allow you to directly
- * add items (avoiding #GMenuItem) for the common cases.
+ * add items (avoiding #GMenuItem) for the common cases. To add
+ * a regular item, use g_menu_insert(). To add a section, use
+ * g_menu_insert_section(). To add a submenu, use
+ * g_menu_insert_submenu().
  *
  * Often it is more convenient to create a #GMenu from an XML
  * fragment, using <link linkend="gio-GMenu-Markup">GMenu Markup</link>.
diff --git a/gio/gmenumodel.c b/gio/gmenumodel.c
index 873a886..9fa187e 100644
--- a/gio/gmenumodel.c
+++ b/gio/gmenumodel.c
@@ -36,8 +36,7 @@
  * have some representation data associated with them, such as labels
  * or icons. Items also have an associated action. The type of the action
  * (ie whether it is stateful, and what kind of state it has) can
- * influence the representation of the item. E.g. an action with a
- * boolean state could be represented as a check menuitem.
+ * influence the representation of the item.
  *
  * FIXME: add a picture here
  *
@@ -63,10 +62,28 @@
  * #G_MENU_ATTRIBUTE_ACTION. The links are used to connect an item with
  * another menu model, which can represent either a section or a submenu,
  * see #G_MENU_LINK_SECTION and #G_MENU_LINK_SUBMENU. To get the #GMenuModel
- * that a link points to, use
- * g_menu_link_iter_get_value().
+ * that a link points to, use g_menu_link_iter_get_value().
  *
  * FIXME: explain how items are associated with actions.
+ *
+ * While a wide variety of stateful actions is possible, the following
+ * states are the minimum that is expected to be supported by all users
+ * of exported menu information:
+ * <variablelist>
+ * <varlistentry>
+ *   <term>Boolean</term>
+ *   <listitem>displayed as a check or switch. Activating the item
+ *     will toggle the state.</listitem>
+ * </varlistentry>
+ * <varlistentry>
+ *   <term>String</term>
+ *   <listitem>displayed as a radio item. Multiple items will usually
+ *     share the same action, each with a string-valued target attribute.
+ *     Activating one of the items will set the state of the action
+ *     to the item's target attribute.
+ *   </listitem>
+ * </varlistentry>
+ * </variablelist>
  */
 
 /**