[glib/wip/menus-rebase2] More docs

[Matthias Clasen <matthiasc src gnome org>]

commit 94f510bb53cfd5e014467a7c2ff313b17d546e8a
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Nov 26 02:02:10 2011 -0500

    More docs
    
    Expand the supported action type documentation. Again based on
    earlier work by Ryan Lortie.

 gio/gactiongroup.c |    7 ++++-
 gio/gmenumodel.c   |   61 +++++++++++++++++++++++++++++++++++++--------------
 2 files changed, 49 insertions(+), 19 deletions(-)
---
diff --git a/gio/gactiongroup.c b/gio/gactiongroup.c
index 7352ec1..7559fb3 100644
--- a/gio/gactiongroup.c
+++ b/gio/gactiongroup.c
@@ -35,12 +35,15 @@
  * method calls, except g_action_group_list_actions() take the name of
  * an action as an argument.
  *
+ * Action groups are often used together with a #GMenuModel that provides
+ * additional representation data for the actions.
+ *
  * The #GActionGroup API is meant to be the 'public' API to the action
  * group.  The calls here are exactly the interaction that 'external
  * forces' (eg: UI, incoming D-Bus messages, etc.) are supposed to have
  * with actions.  'Internal' APIs (ie: ones meant only to be accessed by
  * the action group implementation) are found on subclasses.  This is
- * why you will find -- for example -- g_action_group_get_action_enabled()
+ * why you will find - for example - g_action_group_get_action_enabled()
  * but not an equivalent <function>set()</function> call.
  *
  * Signals are emitted on the action group in response to state changes
@@ -49,7 +52,7 @@
  * Implementations of #GActionGroup should provide implementations for
  * the virtual functions g_action_group_list_actions() and
  * g_action_group_query_action().  The other virtual functions should
- * not be implemented -- their "wrappers" are actually implemented with
+ * not be implemented - their "wrappers" are actually implemented with
  * calls to g_action_group_query_action().
  **/
 
diff --git a/gio/gmenumodel.c b/gio/gmenumodel.c
index 6e75756..4b6d4bc 100644
--- a/gio/gmenumodel.c
+++ b/gio/gmenumodel.c
@@ -103,23 +103,50 @@
  * 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>
+ * is the minimum that is expected to be supported by all users of exported
+ * menu information:
+ * <itemizedlist>
+ * <listitem>an action with no parameter type and no state</listitem>
+ * <listitem>an action with no parameter type and boolean state</listitem>
+ * <listitem>an action with string parameter type and string state</listitem>
+ * </itemizedlist>
+ *
+ * <formalpara><title>Stateless</title>
+ * <para>
+ * A stateless action typically corresponds to an ordinary menu item.
+ * </para>
+ * <para>
+ * Selecting such a menu item will activate the action (with no parameter).
+ * </para>
+ * </formalpara>
+ *
+ * <formalpara><title>Boolean State</title>
+ * <para>
+ * An action with a boolean state will most typically be used with a "toggle"
+ * or "switch" menu item. The state can be set directly, but activating the
+ * action (with no parameter) results in the state being toggled.
+ * </para>
+ * <para>
+ * Selecting a toggle menu item will activate the action. The menu item should
+ * be rendered as "checked" when the state is true.
+ * </para>
+ * </formalpara>
+ *
+ * <formalpara><title>String Parameter and State</title>
+ * <para>
+ * Actions with string parameters and state will most typically be used to
+ * represent an enumerated choice over the items available for a group of
+ * radio menu items. Activating the action with a string parameter is
+ * equivalent to setting that parameter as the state.
+ * </para>
+ * <para>
+ * Radio menu items, in addition to being associated with the action, will
+ * have a target value. Selecting that menu item will result in activation
+ * of the action with the target value as the parameter. The menu item should
+ * be rendered as "selected" when the state of the action is equal to the
+ * target value of the menu item.
+ * </para>
+ * </formalpara>
  */
 
 /**