[glib/wip/gmenu: 47/59] Add GActionMap to the docs

[Ryan Lortie <ryanl src gnome org>]

commit 2875a831e8b3c61c39772c2bddbbf1c1b01361b6
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Nov 30 19:03:41 2011 -0500

    Add GActionMap to the docs

 docs/reference/gio/gio-docs.xml     |    1 +
 docs/reference/gio/gio-sections.txt |   22 +++++++++++-
 docs/reference/gio/gio.types        |    1 +
 gio/gactionmap.c                    |   66 +++++++++++++++++++++++++++++++---
 gio/gsimpleactiongroup.c            |    8 ++--
 5 files changed, 87 insertions(+), 11 deletions(-)
---
diff --git a/docs/reference/gio/gio-docs.xml b/docs/reference/gio/gio-docs.xml
index a157cb6..56e872f 100644
--- a/docs/reference/gio/gio-docs.xml
+++ b/docs/reference/gio/gio-docs.xml
@@ -195,6 +195,7 @@
         <xi:include href="xml/gapplication.xml"/>
         <xi:include href="xml/gapplicationcommandline.xml"/>
         <xi:include href="xml/gactiongroup.xml"/>
+        <xi:include href="xml/gactionmap.xml"/>
         <xi:include href="xml/gsimpleactiongroup.xml"/>
         <xi:include href="xml/gaction.xml"/>
         <xi:include href="xml/gsimpleaction.xml"/>
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index 5f2ddf6..dfbadd1 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -2996,7 +2996,6 @@ g_simple_action_group_insert
 g_simple_action_group_remove
 
 <SUBSECTION>
-GActionEntry
 g_simple_action_group_add_entries
 
 <SUBSECTION Standard>
@@ -3012,6 +3011,27 @@ G_SIMPLE_ACTION_GROUP
 </SECTION>
 
 <SECTION>
+<FILE>gactionmap</FILE>
+<TITLE>GActionMap</TITLE>
+GActionMap
+g_action_map_lookup_action
+GActionEntry
+g_action_map_add_action_entries
+g_action_map_add_action
+g_action_map_remove_action
+
+<SUBSECTION Standard>
+GActionMapInterface
+G_TYPE_ACTION_MAP
+G_ACTION_MAP
+G_IS_ACTION_MAP
+G_ACTION_MAP_GET_IFACE
+
+<SUBSECTION Private>
+g_action_map_get_type
+</SECTION>
+
+<SECTION>
 <FILE>gproxyresolver</FILE>
 <TITLE>GProxyResolver</TITLE>
 GProxyResolver
diff --git a/docs/reference/gio/gio.types b/docs/reference/gio/gio.types
index 62eba2a..0cbbca8 100644
--- a/docs/reference/gio/gio.types
+++ b/docs/reference/gio/gio.types
@@ -1,6 +1,7 @@
 g_action_get_type
 g_simple_action_get_type
 g_action_group_get_type
+g_action_map_get_type
 g_simple_action_group_get_type
 g_app_info_get_type
 g_app_launch_context_get_type
diff --git a/gio/gactionmap.c b/gio/gactionmap.c
index 8557f61..692c176 100644
--- a/gio/gactionmap.c
+++ b/gio/gactionmap.c
@@ -26,6 +26,22 @@
 #include "gactionmap.h"
 #include "gaction.h"
 
+/**
+ * SECTION:gactionmap
+ * @title: GActionMap
+ * @short_description: Interface for action containers
+ *
+ * The GActionMap interface is implemented by #GActionGroup
+ * implementations that operate by containing a number of
+ * named #GAction instances, such as #GSimpleActionGroup.
+ *
+ * One useful application of this interface is to map the
+ * names of actions from various action groups to unique,
+ * prefixed names (e.g. by prepending "app." or "win.").
+ * This is the motivation for the 'Map' part of the interface
+ * name.
+ */
+
 G_DEFINE_INTERFACE (GActionMap, g_action_map, G_TYPE_ACTION_GROUP)
 
 static void
@@ -33,6 +49,19 @@ g_action_map_default_init (GActionMapInterface *iface)
 {
 }
 
+/**
+ * g_action_map_lookup_action:
+ * @action_map: a #GActionMap
+ * @action_name: the name of an action
+ *
+ * Looks up the action with the name @action_name in @action_map.
+ *
+ * If no such action exists, returns %NULL.
+ *
+ * Returns: (transfer none): a #GAction, or %NULL
+ *
+ * Since: 2.32
+ */
 GAction *
 g_action_map_lookup_action (GActionMap  *action_map,
                             const gchar *action_name)
@@ -41,14 +70,39 @@ g_action_map_lookup_action (GActionMap  *action_map,
     ->lookup_action (action_map, action_name);
 }
 
+/**
+ * g_action_map_add_action:
+ * @action_map: a #GActionMap
+ * @action: a #GAction
+ *
+ * Adds an action to the @action_map.
+ *
+ * If the action map already contains an action with the same name
+ * as @action then the old action is dropped from the action map.
+ *
+ * The action map takes its own reference on @action.
+ *
+ * Since: 2.32
+ */
 void
-g_action_map_add_action (GActionMap  *action_map,
-                         GAction     *action)
+g_action_map_add_action (GActionMap *action_map,
+                         GAction    *action)
 {
   return G_ACTION_MAP_GET_IFACE (action_map)
     ->add_action (action_map, action);
 }
 
+/**
+ * g_action_map_remove_action:
+ * @action_map: a #GActionMap
+ * @action_name: the name of the action
+ *
+ * Removes the named action from the action map.
+ *
+ * If no action of this name is in the map then nothing happens.
+ *
+ * Since: 2.32
+ */
 void
 g_action_map_remove_action (GActionMap  *action_map,
                             const gchar *action_name)
@@ -86,10 +140,10 @@ g_action_map_remove_action (GActionMap  *action_map,
 
 /**
  * g_action_map_add_action_entries:
- * @simple: a #GSimpleActionGroup
+ * @action_map: a #GActionMap
  * @entries: a pointer to the first item in an array of #GActionEntry
  *           structs
- * @n_entries: the length of @entries, or -1
+ * @n_entries: the length of @entries, or -1 if @entries is %NULL-terminated
  * @user_data: the user data for signal connections
  *
  * A convenience function for creating multiple #GSimpleAction instances
@@ -133,8 +187,8 @@ g_action_map_remove_action (GActionMap  *action_map,
  * </programlisting>
  * </example>
  *
- * Since: 2.30
- **/
+ * Since: 2.32
+ */
 void
 g_action_map_add_action_entries (GActionMap         *action_map,
                                  const GActionEntry *entries,
diff --git a/gio/gsimpleactiongroup.c b/gio/gsimpleactiongroup.c
index ec991be..f775279 100644
--- a/gio/gsimpleactiongroup.c
+++ b/gio/gsimpleactiongroup.c
@@ -31,7 +31,7 @@
  * @short_description: A simple GActionGroup implementation
  *
  * #GSimpleActionGroup is a hash table filled with #GAction objects,
- * implementing the #GActionGroup interface.
+ * implementing the #GActionGroup and #GActionMap interfaces.
  **/
 
 struct _GSimpleActionGroupPrivate
@@ -44,9 +44,9 @@ static void g_simple_action_group_map_iface_init (GActionMapInterface *);
 G_DEFINE_TYPE_WITH_CODE (GSimpleActionGroup,
   g_simple_action_group, G_TYPE_OBJECT,
   G_IMPLEMENT_INTERFACE (G_TYPE_ACTION_GROUP,
-    g_simple_action_group_iface_init);
+                         g_simple_action_group_iface_init);
   G_IMPLEMENT_INTERFACE (G_TYPE_ACTION_MAP,
-    g_simple_action_group_map_iface_init))
+                         g_simple_action_group_map_iface_init))
 
 static gchar **
 g_simple_action_group_list_actions (GActionGroup *group)
@@ -310,7 +310,7 @@ g_simple_action_group_new (void)
  * Returns: (transfer none): a #GAction, or %NULL
  *
  * Since: 2.28
- **/
+ */
 GAction *
 g_simple_action_group_lookup (GSimpleActionGroup *simple,
                               const gchar        *action_name)