[glib/wip/menus: 7/18] Document all the things

[Ryan Lortie <ryanl src gnome org>]

commit e47c8f21fd7391cfabafda274807202959ccd0ca
Author: Ryan Lortie <desrt desrt ca>
Date:   Mon Jul 11 01:51:59 2011 +0200

    Document all the things

 gio/gmenu.c       |  469 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 gio/gmenumarkup.c |   85 ++++++++++
 gio/gmenumodel.c  |  353 +++++++++++++++++++++++++++++++++++++++-
 3 files changed, 903 insertions(+), 4 deletions(-)
---
diff --git a/gio/gmenu.c b/gio/gmenu.c
index 03bf5d3..e6ef55f 100644
--- a/gio/gmenu.c
+++ b/gio/gmenu.c
@@ -11,6 +11,19 @@
 
 #include <string.h>
 
+/**
+ * SECTION:gmenu
+ * @title: GMenu
+ * @short_description: a simple implementation of #GMenuModel
+ *
+ * #GMenu is a simple implementation of #GMenuModel.
+ *
+ * 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.
+ **/
+
 struct _GMenuItem
 {
   GObject parent_instance;
@@ -76,6 +89,30 @@ g_menu_get_item_links (GMenuModel  *model,
   *quark_table = g_array_index (menu->priv->items, struct item, position).links;
 }
 
+/**
+ * g_menu_insert_item:
+ * @menu: a #GMenu
+ * @position: the position at which to insert the item
+ * @item: the #GMenuItem to insert
+ *
+ * Inserts @item into @menu.
+ *
+ * The "insertion" is actually done by copying all of the attribute and
+ * link values of @item and using them to form a new item within @menu.
+ * As such, @item itself is not really inserted, but rather, a menu item
+ * that is exactly the same as the one presently described by @item.
+ *
+ * This means that @item is essentially useless after the insertion
+ * occurs.  Any changes you make to it are ignored unless it is inserted
+ * again (at which point its updated values will be copied).
+ *
+ * You should probably just free @item once you're done.
+ *
+ * There are many convenience functions to take care of common cases.
+ * See g_menu_insert(), g_menu_insert_section() and
+ * g_menu_insert_submenu() as well as "prepend" and "append" variants of
+ * each of these functions.
+ **/
 void
 g_menu_insert_item (GMenu     *menu,
                     gint       position,
@@ -98,6 +135,15 @@ g_menu_insert_item (GMenu     *menu,
   g_menu_model_items_changed (G_MENU_MODEL (menu), position, 0, 1);
 }
 
+/**
+ * g_menu_prepend_item:
+ * @menu: a #GMenu
+ * @item: a #GMenuItem to prepend
+ *
+ * Prepends @item to the start of @menu.
+ *
+ * See g_menu_insert_item() for more information.
+ **/
 void
 g_menu_prepend_item (GMenu     *menu,
                      GMenuItem *item)
@@ -105,6 +151,15 @@ g_menu_prepend_item (GMenu     *menu,
   g_menu_insert_item (menu, 0, item);
 }
 
+/**
+ * g_menu_append_item:
+ * @menu: a #GMenu
+ * @item: a #GMenuItem to append
+ *
+ * Appends @item to the end of @menu.
+ *
+ * See g_menu_insert_item() for more information.
+ **/
 void
 g_menu_append_item (GMenu     *menu,
                     GMenuItem *item)
@@ -112,6 +167,19 @@ g_menu_append_item (GMenu     *menu,
   g_menu_insert_item (menu, -1, item);
 }
 
+/**
+ * g_menu_freeze:
+ * @menu: a #GMenu
+ *
+ * Marks @menu as frozen.
+ *
+ * After the menu is frozen, it is an error to attempt to make any
+ * changes to it.  In effect this means that the #GMenu API must no
+ * longer be used.
+ *
+ * This function causes g_menu_model_is_mutable() to begin returning
+ * %TRUE, which has some positive performance implications.
+ **/
 void
 g_menu_freeze (GMenu *menu)
 {
@@ -120,12 +188,32 @@ g_menu_freeze (GMenu *menu)
   menu->priv->mutable = FALSE;
 }
 
+/**
+ * g_menu_new:
+ *
+ * Creates a new #GMenu.
+ *
+ * The new menu has no items.
+ *
+ * Returns: a new #GMenu
+ **/
 GMenu *
 g_menu_new (void)
 {
   return g_object_new (G_TYPE_MENU, NULL);
 }
 
+/**
+ * g_menu_insert:
+ * @menu: a #GMenu
+ * @position: the position at which to insert the item
+ * @label: (allow-none): the section label, or %NULL
+ * @detailed_action: (allow-none): the detailed action string, or %NULL
+ *
+ * Convenience function for inserting a normal menu item into @menu.
+ * Combine g_menu_new() and g_menu_insert_item() for a more flexible
+ * alternative.
+ **/
 void
 g_menu_insert (GMenu       *menu,
                gint         position,
@@ -139,7 +227,16 @@ g_menu_insert (GMenu       *menu,
   g_object_unref (menu_item);
 }
 
-
+/**
+ * g_menu_prepend:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @detailed_action: (allow-none): the detailed action string, or %NULL
+ *
+ * Convenience function for prepending a normal menu item to the start
+ * of @menu.  Combine g_menu_new() and g_menu_insert_item() for a more
+ * flexible alternative.
+ **/
 void
 g_menu_prepend (GMenu       *menu,
                 const gchar *label,
@@ -148,6 +245,16 @@ g_menu_prepend (GMenu       *menu,
   g_menu_insert (menu, 0, label, detailed_action);
 }
 
+/**
+ * g_menu_append:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @detailed_action: (allow-none): the detailed action string, or %NULL
+ *
+ * Convenience function for appending a normal menu item to the end of
+ * @menu.  Combine g_menu_new() and g_menu_insert_item() for a more
+ * flexible alternative.
+ **/
 void
 g_menu_append (GMenu       *menu,
                const gchar *label,
@@ -156,7 +263,17 @@ g_menu_append (GMenu       *menu,
   g_menu_insert (menu, -1, label, detailed_action);
 }
 
-
+/**
+ * g_menu_insert_section:
+ * @menu: a #GMenu
+ * @position: the position at which to insert the item
+ * @label: (allow-none): the section label, or %NULL
+ * @section: a #GMenuModel with the items of the section
+ *
+ * Convenience function for inserting a section menu item into @menu.
+ * Combine g_menu_new_section() and g_menu_insert_item() for a more
+ * flexible alternative.
+ **/
 void
 g_menu_insert_section (GMenu       *menu,
                        gint         position,
@@ -171,6 +288,17 @@ g_menu_insert_section (GMenu       *menu,
 }
 
 
+/**
+ * g_menu_prepend_section:
+ * @menu: a #GMenu
+ * @position: the position at which to insert the item
+ * @label: (allow-none): the section label, or %NULL
+ * @section: a #GMenuModel with the items of the section
+ *
+ * Convenience function for prepending a section menu item to the start
+ * of @menu.  Combine g_menu_new_section() and g_menu_insert_item() for
+ * a more flexible alternative.
+ **/
 void
 g_menu_prepend_section (GMenu       *menu,
                         const gchar *label,
@@ -179,6 +307,17 @@ g_menu_prepend_section (GMenu       *menu,
   g_menu_insert_section (menu, 0, label, section);
 }
 
+/**
+ * g_menu_append_section:
+ * @menu: a #GMenu
+ * @position: the position at which to insert the item
+ * @label: (allow-none): the section label, or %NULL
+ * @section: a #GMenuModel with the items of the section
+ *
+ * Convenience function for appending a section menu item to the end of
+ * @menu.  Combine g_menu_new_section() and g_menu_insert_item() for a
+ * more flexible alternative.
+ **/
 void
 g_menu_append_section (GMenu       *menu,
                        const gchar *label,
@@ -187,6 +326,17 @@ g_menu_append_section (GMenu       *menu,
   g_menu_insert_section (menu, -1, label, section);
 }
 
+/**
+ * g_menu_insert_submenu:
+ * @menu: a #GMenu
+ * @position: the position at which to insert the item
+ * @label: (allow-none): the section label, or %NULL
+ * @submenu: a #GMenuModel with the items of the submenu
+ *
+ * Convenience function for inserting a submenu menu item into @menu.
+ * Combine g_menu_new_submenu() and g_menu_insert_item() for a more
+ * flexible alternative.
+ **/
 void
 g_menu_insert_submenu (GMenu       *menu,
                        gint         position,
@@ -200,6 +350,16 @@ g_menu_insert_submenu (GMenu       *menu,
   g_object_unref (menu_item);
 }
 
+/**
+ * g_menu_prepend_submenu:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @submenu: a #GMenuModel with the items of the submenu
+ *
+ * Convenience function for prepending a submenu menu item to the start
+ * of @menu.  Combine g_menu_new_submenu() and g_menu_insert_item() for
+ * a more flexible alternative.
+ **/
 void
 g_menu_prepend_submenu (GMenu       *menu,
                         const gchar *label,
@@ -208,6 +368,16 @@ g_menu_prepend_submenu (GMenu       *menu,
   g_menu_insert_submenu (menu, 0, label, submenu);
 }
 
+/**
+ * g_menu_append_submenu:
+ * @menu: a #GMenu
+ * @label: (allow-none): the section label, or %NULL
+ * @submenu: a #GMenuModel with the items of the submenu
+ *
+ * Convenience function for appending a submenu menu item to the end of
+ * @menu.  Combine g_menu_new_submenu() and g_menu_insert_item() for a
+ * more flexible alternative.
+ **/
 void
 g_menu_append_submenu (GMenu       *menu,
                        const gchar *label,
@@ -225,6 +395,22 @@ g_menu_clear_item (struct item *item)
     g_hash_table_unref (item->links);
 }
 
+/**
+ * g_menu_remove:
+ * @menu: a #GMenu
+ * @position: the position of the item to remove
+ *
+ * Removes an item from the menu.
+ *
+ * @position gives the index of the item to remove.
+ *
+ * It is an error if position is not in range the range from 0 to one
+ * less than the number of items in the menu.
+ *
+ * It is not possible to remove items by identity since items are added
+ * to the menu simply by copying their links and attributes (ie:
+ * identity of the item itself is not preserved).
+ **/
 void
 g_menu_remove (GMenu *menu,
                gint   index_)
@@ -334,6 +520,22 @@ g_menu_item_class_init (GMenuItemClass *class)
   class->finalize = g_menu_item_finalize;
 }
 
+/**
+ * g_menu_item_set_attribute_value:
+ * @menu_item: a #GMenuItem
+ * @attribute: the attribute to set
+ * @value: (allow-none): a #GVariant to use as the value, or %NULL
+ *
+ * Sets or unsets an attribute on @menu_item.
+ *
+ * The attribute to set or unset is specified by @attribute.
+ *
+ * If @value is non-%NULL then it is used as the new value for the
+ * attribute.  If @value is %NULL then the attribute is unset.
+ *
+ * See also g_menu_item_set_attribute() for a more convenient way to do
+ * the same.
+ **/
 void
 g_menu_item_set_attribute_value (GMenuItem *menu_item,
                                  GQuark     attribute,
@@ -350,6 +552,25 @@ g_menu_item_set_attribute_value (GMenuItem *menu_item,
     g_hash_table_remove (menu_item->attributes, GINT_TO_POINTER (attribute));
 }
 
+/**
+ * g_menu_item_set_attribute:
+ * @menu_item: a #GMenuItem
+ * @attribute: the attribute to set
+ * @format_string: (allow-none): a #GVariant format string, or %NULL
+ * @...: positional parameters, as per @format_string
+ *
+ * Sets or unsets an attribute on @menu_item.
+ *
+ * The attribute to set or unset is specified by @attribute.
+ *
+ * If @format_string is non-%NULL then the proper position parameters
+ * are collected to create a #GVariant instance to use as the attribute
+ * value.  If it is %NULL then the positional parameterrs are ignored
+ * and the named attribute is unset.
+ *
+ * See also g_menu_item_set_attribute_value() for an equivalent call
+ * that directly accepts a #GVariant.
+ **/
 void
 g_menu_item_set_attribute (GMenuItem   *menu_item,
                            GQuark       attribute,
@@ -372,6 +593,22 @@ g_menu_item_set_attribute (GMenuItem   *menu_item,
   g_menu_item_set_attribute_value (menu_item, attribute, value);
 }
 
+/**
+ * g_menu_item_set_link:
+ * @menu_item: a #GMenuItem
+ * @link: a #GQuark naming the link to establish or unset
+ * @model: (allow-none): the #GMenuModel to link to (or %NULL to unset)
+ *
+ * Creates a link from @menu_item to @link if non-%NULL, or unsets it.
+ *
+ * @link is a #GQuark that, when converted to a string, gives the
+ * name of the link to set.  Some commonly-used link quarks are provided
+ * as constants, such as %G_MENU_LINK_SUBMENU and %G_MENU_LINK_SECTION.
+ *
+ * Links are used to establish a relationship between a particular menu
+ * item and another menu.  For example, %G_MENU_LINK_SUBMENU is used to
+ * associate a submenu with a particular menu item.
+ **/
 void
 g_menu_item_set_link (GMenuItem  *menu_item,
                       GQuark      link,
@@ -388,6 +625,16 @@ g_menu_item_set_link (GMenuItem  *menu_item,
     g_hash_table_remove (menu_item->links, GINT_TO_POINTER (link));
 }
 
+/**
+ * g_menu_item_set_label:
+ * @menu_item: a #GMenuItem
+ * @label: (allow-none): the label to set, or %NULL to unset
+ *
+ * Sets or unsets the "label" attribute of @menu_item.
+ *
+ * If @label is non-%NULL it is used as the label for the menu item.  If
+ * it is %NULL then the label attribute is unset.
+ **/
 void
 g_menu_item_set_label (GMenuItem   *menu_item,
                        const gchar *label)
@@ -402,6 +649,19 @@ g_menu_item_set_label (GMenuItem   *menu_item,
   g_menu_item_set_attribute_value (menu_item, G_MENU_ATTRIBUTE_LABEL, value);
 }
 
+/**
+ * g_menu_item_set_submenu:
+ * @menu_item: a #GMenuItem
+ * @submenu: (allow-none): a #GMenuModel, or %NULL
+ *
+ * Sets or unsets the "submenu" link of @menu_item to @submenu.
+ *
+ * If @submenu is non-%NULL, it is linked to.  If it is %NULL then the
+ * link is unset.
+ *
+ * The effect of having one menu appear as a submenu of another is
+ * exactly as it sounds.
+ **/
 void
 g_menu_item_set_submenu (GMenuItem  *menu_item,
                          GMenuModel *submenu)
@@ -409,6 +669,19 @@ g_menu_item_set_submenu (GMenuItem  *menu_item,
   g_menu_item_set_link (menu_item, G_MENU_LINK_SUBMENU, submenu);
 }
 
+/**
+ * g_menu_item_set_section:
+ * @menu_item: a #GMenuItem
+ * @section: (allow-none): a #GMenuModel, or %NULL
+ *
+ * Sets or unsets the "section" link of @menu_item to @section.
+ *
+ * The effect of having one menu appear as a section of another is
+ * exactly as it sounds: the items from @section become a direct part of
+ * the menu that @menu_item is added to.  See g_menu_item_new_section()
+ * for more information about what it means for a menu item to be a
+ * section.
+ **/
 void
 g_menu_item_set_section (GMenuItem  *menu_item,
                          GMenuModel *section)
@@ -416,6 +689,49 @@ g_menu_item_set_section (GMenuItem  *menu_item,
   g_menu_item_set_link (menu_item, G_MENU_LINK_SECTION, section);
 }
 
+/**
+ * g_menu_item_set_action_and_target_value:
+ * @menu_item: a #GMenuItem
+ * @action: (allow-none): the name of the action for this item
+ * @target_value: (allow-none): a #GVariant to use as the action target
+ *
+ * Sets or unsets the "action" and "target" attributes of @menu_item.
+ *
+ * If @action is %NULL then both the "action" and "target" attributes
+ * are unset (and @target_value is ignored).
+ *
+ * If @action is non-%NULL then the "action" attribute is set.  The
+ * "target" attribute is then set to the value of @target_value if it is
+ * non-%NULL or unset otherwise.
+ *
+ * Normal menu items (ie: not submenu, section or other custom item
+ * types) are expected to have the "action" attribute set to identify
+ * the action that they are associated with.  The state type of the
+ * action help to determine the disposition of the menu item.  See
+ * #GAction and #GActionGroup for an overview of actions.
+ *
+ * In general, clicking on the menu item will result in activation of
+ * the named action with the "target" attribute given as the parameter
+ * to the action invocation.  If the "target" attribute is not set then
+ * the action is invoked with no parameter.
+ *
+ * If the action has no state then the menu item is usually drawn as a
+ * plain menu item (ie: with no additional decoration).
+ *
+ * If the action has a boolean state then the menu item is usually drawn
+ * as a toggle menu item (ie: with a checkmark or equivalent
+ * indication).  The item should be marked as 'toggled' or 'checked'
+ * when the boolean state is %TRUE.
+ *
+ * If the action has a string state then the menu item is usually drawn
+ * as a radio menu item (ie: with a radio bullet or equivalent
+ * indication).  The item should be marked as 'selected' when the string
+ * state is equal to the value of the @target property.
+ *
+ * See g_menu_item_set_action_and_target() or
+ * g_menu_item_set_detailed_action() for two equivalent calls that are
+ * probably more convenient for most uses.
+ */
 void
 g_menu_item_set_action_and_target_value (GMenuItem   *menu_item,
                                          const gchar *action,
@@ -437,6 +753,33 @@ g_menu_item_set_action_and_target_value (GMenuItem   *menu_item,
   g_menu_item_set_attribute_value (menu_item, G_MENU_ATTRIBUTE_TARGET, target_value);
 }
 
+/**
+ * g_menu_item_set_action_and_target:
+ * @menu_item: a #GMenuItem
+ * @action: (allow-none): the name of the action for this item
+ * @format_string: (allow-none): a GVariant format string
+ * @...: positional parameters, as per @format_string
+ *
+ * Sets or unsets the "action" and "target" attributes of @menu_item.
+ *
+ * If @action is %NULL then both the "action" and "target" attributes
+ * are unset (and @format_string is ignored along with the positional
+ * parameters).
+ *
+ * If @action is non-%NULL then the "action" attribute is set.
+ * @format_string is then inspected.  If it is non-%NULL then the proper
+ * position parameters are collected to create a #GVariant instance to
+ * use as the target value.  If it is %NULL then the positional
+ * parameterrs are ignored and the "target" attribute is unset.
+ *
+ * See also g_menu_item_set_action_and_target_value() for an equivalent
+ * call that directly accepts a #GVariant.  See
+ * g_menu_item_set_detailed_action() for a more equivalent version that
+ * works with string-typed targets.
+ *
+ * See also g_menu_set_action_and_target_value() for a description of
+ * the semantics of the action and target attributes.
+ **/
 void
 g_menu_item_set_action_and_target (GMenuItem   *menu_item,
                                    const gchar *action,
@@ -459,6 +802,30 @@ g_menu_item_set_action_and_target (GMenuItem   *menu_item,
   g_menu_item_set_action_and_target_value (menu_item, action, value);
 }
 
+/**
+ * g_menu_item_set_detailed_action:
+ * @menu_item: a #GMenuItem
+ * @detailed_action: the "detailed" action string
+ *
+ * Sets the "action" and possibly the "target" attribute of @menu_item.
+ *
+ * If @detailed_action contains a double colon ("::") then it is used as
+ * a separator between an action name and a target string.  In this
+ * case, this call is equivalent to calling
+ * g_menu_item_set_action_and_target() with the part before the "::" and
+ * g_menu_item_set_target_value() with a string-type #GVariant
+ * containing the part following the "::".
+ *
+ * If @detailed_action doesn't contain "::" then the action is set to
+ * the given string (verbatim) and the target value is unset.
+ *
+ * See g_menu_item_set_action_and_target() or
+ * g_menu_item_set_action_and_target_value() for more flexible (but
+ * slightly less convenient) alternatives.
+ *
+ * See also g_menu_set_action_and_target_value() for a description of
+ * the semantics of the action and target attributes.
+ **/
 void
 g_menu_item_set_detailed_action (GMenuItem   *menu_item,
                                  const gchar *detailed_action)
@@ -480,6 +847,22 @@ g_menu_item_set_detailed_action (GMenuItem   *menu_item,
     g_menu_item_set_action_and_target_value (menu_item, detailed_action, NULL);
 }
 
+/**
+ * g_menu_item_new:
+ * @label: (allow-none): the section label, or %NULL
+ * @detailed_action: (allow-none): the detailed action string, or %NULL
+ *
+ * Creates a new #GMenuItem.
+ *
+ * If @label is non-%NULL it is used to set the "label" attribute of the
+ * new item.
+ *
+ * If @detailed_action is non-%NULL it is used to set the "action" and
+ * possibly the "target" attribute of the new item.  See
+ * g_menu_item_set_detailed_action() for more information.
+ *
+ * Returns: a new #GMenuItem
+ **/
 GMenuItem *
 g_menu_item_new (const gchar *label,
                  const gchar *detailed_action)
@@ -497,6 +880,18 @@ g_menu_item_new (const gchar *label,
   return menu_item;
 }
 
+/**
+ * g_menu_item_new_submenu:
+ * @label: (allow-none): the section label, or %NULL
+ * @submenu: a #GMenuModel with the items of the submenu
+ *
+ * Creates a new #GMenuItem representing a submenu.
+ *
+ * This is a convenience API around g_menu_item_new() and
+ * g_menu_item_set_submenu().
+ *
+ * Returns: a new #GMenuItem
+ **/
 GMenuItem *
 g_menu_item_new_submenu (const gchar *label,
                          GMenuModel  *submenu)
@@ -513,6 +908,76 @@ g_menu_item_new_submenu (const gchar *label,
   return menu_item;
 }
 
+/**
+ * g_menu_item_new_section:
+ * @label: (allow-none): the section label, or %NULL
+ * @section: a #GMenuModel with the items of the section
+ *
+ * Creates a new #GMenuItem representing a section.
+ *
+ * This is a convenience API around g_menu_item_new() and
+ * g_menu_item_set_section().
+ *
+ * The effect of having one menu appear as a section of another is
+ * exactly as it sounds: the items from @section become a direct part of
+ * the menu that @menu_item is added to.
+ *
+ * Visual separation is typically displayed between two non-empty
+ * sections.  If @label is non-%NULL then it will be encorporated into
+ * this visual indication.  This allows for labeled subsections of a
+ * menu.
+ *
+ * As a simple example, consider a typical "Edit" menu from a simple
+ * program.  It probably contains an "Undo" and "Redo" item, followed by
+ * a separator, followed by "Cut", "Copy" and "Paste".
+ *
+ * This would be accomplished by creating three #GMenu instances.  The
+ * first would be populated with the "Undo" and "Redo" items, and the
+ * second with the "Cut", "Copy" and "Paste" items.  The first and
+ * second menus would then be added as submenus of the third.  In XML
+ * format, this would look something like the following:
+ *
+ * <informalexample><programlisting><![CDATA[
+ * <menu id='edit-menu'>
+ *   <section>
+ *     <item label='Undo'/>
+ *     <item label='Redo'/>
+ *   </section>
+ *   <section>
+ *     <item label='Cut'/>
+ *     <item label='Copy'/>
+ *     <item label='Paste'/>
+ *   </section>
+ * </menu>
+ * ]]></programlisting></informalexample>
+ *
+ * The following example is exactly equivalent.  It is more illustrative
+ * of the exact relationship between the menus and items (keeping in
+ * mind that the 'link' element defines a new menu that is linked to the
+ * containing one).  The style of the second example is more verbose and
+ * difficult to read (and therefore not recommended except for the
+ * purpose of understanding what is really going on).
+ *
+ * <informalexample><programlisting><![CDATA[
+ * <menu id='edit-menu'>
+ *   <item>
+ *     <link name='section'>
+ *       <item label='Undo'/>
+ *       <item label='Redo'/>
+ *     </link>
+ *   </item>
+ *   <item>
+ *     <link name='section'>
+ *       <item label='Cut'/>
+ *       <item label='Copy'/>
+ *       <item label='Paste'/>
+ *     </link>
+ *   </item>
+ * </menu>
+ * ]]></programlisting></informalexample>
+ *
+ * Returns: a new #GMenuItem
+ **/
 GMenuItem *
 g_menu_item_new_section (const gchar *label,
                          GMenuModel  *section)
diff --git a/gio/gmenumarkup.c b/gio/gmenumarkup.c
index c84bf34..c6591d9 100644
--- a/gio/gmenumarkup.c
+++ b/gio/gmenumarkup.c
@@ -9,6 +9,15 @@
 
 #include <gi18n.h>
 
+/**
+ * SECTION:gmenumarkup
+ * @title: GMenu Markup
+ * @short_description: parsing and printing #GMenuModel XML
+ *
+ * There is a standard XML format for #GMenuModel that will be
+ * documented here.
+ **/
+
 struct frame
 {
   GMenu        *menu;
@@ -316,6 +325,26 @@ static GMarkupParser g_menu_subparser =
   g_menu_markup_error
 };
 
+/**
+ * g_menu_markup_parser_start:
+ * @context: a #GMarkupParseContext
+ * @objects: (allow-none): a #GHashTable for the objects, or %NULL
+ *
+ * Begin parsing a group of menus in XML form.
+ *
+ * If @objects is specified then it must be a #GHashTable that was
+ * created using g_hash_table_new() with g_str_hash(), g_str_equal(),
+ * g_free() and g_object_unref().  Any named menus that are encountered
+ * while parsing will be added to this table.  Each toplevel menu must
+ * be named.
+ *
+ * If @objects is %NULL then an empty hash table will be created.
+ *
+ * This function should be called from the start_element function for
+ * the element representing the group containing the menus.  In other
+ * words, the content inside of this element is expected to be a list of
+ * menus.
+ **/
 void
 g_menu_markup_parser_start (GMarkupParseContext *context,
                             GHashTable          *objects)
@@ -334,6 +363,21 @@ g_menu_markup_parser_start (GMarkupParseContext *context,
   g_markup_parse_context_push (context, &g_menu_subparser, state);
 }
 
+/**
+ * g_menu_markup_parser_end:
+ * @context: a #GMarkupParseContext
+ *
+ * Stop the parsing of a set of menus and return the #GHashTable.
+ *
+ * The #GHashTable maps strings to #GObject instances.  The parser only
+ * adds #GMenu instances to the table, but it may contain other types if
+ * a table was provided to g_markup_parser_start().
+ *
+ * This call should be matched with g_menu_markup_parser_start().  See
+ * that function for more information
+ *
+ * Returns: (transfer full): the #GHashTable containing the objects
+ **/
 GHashTable *
 g_menu_markup_parser_end (GMarkupParseContext *context)
 {
@@ -346,6 +390,28 @@ g_menu_markup_parser_end (GMarkupParseContext *context)
   return objects;
 }
 
+/**
+ * g_menu_markup_parser_start_menu:
+ * @context: a #GMarkupParseContext
+ * @objects: (allow-none): a #GHashTable for the objects, or %NULL
+ *
+ * Begin parsing the XML definition of a menu.
+ *
+ * This function should be called from the start_element function for
+ * the element representing the menu itself.  In other words, the
+ * content inside of this element is expected to be a list of items.
+ *
+ * If @objects is specified then it must be a #GHashTable that was
+ * created using g_hash_table_new() with g_str_hash(), g_str_equal(),
+ * g_free() and g_object_unref().  Any named menus that are encountered
+ * while parsing will be added to this table.
+ *
+ * If @object is %NULL then named menus will not be supported.
+ *
+ * You should call g_menu_markup_parser_end_menu() from the
+ * corresponding end_element function in order to collect the newly
+ * parsed menu.
+ **/
 void
 g_menu_markup_parser_start_menu (GMarkupParseContext *context,
                                  GHashTable          *objects)
@@ -364,6 +430,17 @@ g_menu_markup_parser_start_menu (GMarkupParseContext *context,
   state->frame.menu = g_menu_new ();
 }
 
+/**
+ * g_menu_markup_parser_end_menu:
+ * @context: a #GMarkupParseContext
+ *
+ * Stop the parsing of a menu and return the newly-created #GMenu.
+ *
+ * This call should be matched with g_menu_markup_parser_start_menu().
+ * See that function for more information
+ *
+ * Returns: (transfer full): the newly-created #GMenu
+ **/
 GMenu *
 g_menu_markup_parser_end_menu (GMarkupParseContext *context)
 {
@@ -467,6 +544,14 @@ g_menu_markup_print_string (GString    *string,
   return string;
 }
 
+/**
+ * g_menu_markup_print_stderr:
+ * @model: a #GMenuModel
+ *
+ * Print @model to stderr for debugging purposes.
+ *
+ * This debugging function will be removed in the future.
+ **/
 void
 g_menu_markup_print_stderr (GMenuModel *model)
 {
diff --git a/gio/gmenumodel.c b/gio/gmenumodel.c
index 5e33805..ac11333 100644
--- a/gio/gmenumodel.c
+++ b/gio/gmenumodel.c
@@ -7,6 +7,14 @@
 
 #include "gmenumodel.h"
 
+/**
+ * SECTION:gmenumodel
+ * @title: GMenuModel
+ * @short_description: an interface representing the contents of a menu
+ *
+ * #GMenuModel represents the contents of a menu -- an ordered list of
+ * menu items.
+ **/
 
 typedef struct
 {
@@ -395,8 +403,18 @@ g_menu_model_class_init (GMenuModelClass *class)
                   3, G_TYPE_INT, G_TYPE_INT, G_TYPE_INT);
 }
 
-
-
+/**
+ * g_menu_model_is_mutable:
+ * @model: a #GMenuModel
+ *
+ * Queries if @model is mutable.
+ *
+ * An immutable #GMenuModel will never emit the "items-changed" signal.
+ * Consumers of the model may make optimisations accordingly.
+ *
+ * Returns: %TRUE if the model is mutable (ie: "items-changed" may be
+ *          emitted).
+ **/
 gboolean
 g_menu_model_is_mutable (GMenuModel *model)
 {
@@ -404,6 +422,14 @@ g_menu_model_is_mutable (GMenuModel *model)
     ->is_mutable (model);
 }
 
+/**
+ * g_menu_model_get_n_items:
+ * @model: a #GMenuModel
+ *
+ * Query the number of items in @model.
+ *
+ * Returns: the number of items
+ **/
 gint
 g_menu_model_get_n_items (GMenuModel *model)
 {
@@ -411,6 +437,25 @@ g_menu_model_get_n_items (GMenuModel *model)
     ->get_n_items (model);
 }
 
+/**
+ * g_menu_model_get_item:
+ * @model: a #GMenuModel
+ * @item_index: the index of the item to get
+ * @item: a #GMenuModelItem structure to store the item
+ *
+ * Initialises a #GMenuModelItem structure to act as a pointer to the
+ * item at position @item_index in @model.
+ *
+ * The #GMenuModelItem will typically be stack-allocated.  It remains
+ * valid only for as long as the model exists and does not change.  The
+ * model is guaranteed not to change without returning to the mainloop
+ * so it is quite safe to assume that a stack-allocated #GMenuModelItem
+ * will remain valid for as long as it is in scope (as long as the
+ * #GMenuModel is not destroyed).
+ *
+ * The #GMenuModelItem need not be initialised to any particular value
+ * and does not need to be freed.
+ **/
 void
 g_menu_model_get_item (GMenuModel     *model,
                        gint            item_index,
@@ -422,6 +467,18 @@ g_menu_model_get_item (GMenuModel     *model,
   item->position = item_index;
 }
 
+/**
+ * g_menu_model_iterate_item_attributes:
+ * @model: a #GMenuModel
+ * @item_index: the index of the item
+ *
+ * Creates a #GMenuLinkIter to iterate over the links of the item at
+ * position @item_index in @model.
+ *
+ * You must free the iterator with g_object_unref() when you are done.
+ *
+ * Returns: (transfer full): a new #GMenuLinkIter
+ **/
 GMenuAttributeIter *
 g_menu_model_iterate_item_attributes (GMenuModel *model,
                                       gint        item_index)
@@ -430,6 +487,28 @@ g_menu_model_iterate_item_attributes (GMenuModel *model,
     ->iterate_item_attributes (model, item_index);
 }
 
+/**
+ * g_menu_model_get_item_attribute_value:
+ * @model: a #GMenuModel
+ * @item_index: the index of the item
+ * @attribute: the attribute to query
+ * @expected_type: (allow-none): the expected type of the attribute, or
+ *                               %NULL
+ *
+ * Queries the item at position @item_index in @model for the attribute
+ * specified by @attribute.
+ *
+ * If @expected_type is non-%NULL then it specifies the expected type of
+ * the attribute.  If it is %NULL then any type will be accepted.
+ *
+ * If the attribute exists and matches @expected_type (or if the
+ * expected type is unspecified) then the value is returned.
+ *
+ * If the attribute does not exist, or does not match the expected type
+ * then %NULL is returned.
+ *
+ * Returns: (transfer full): the value of the attribute
+ **/
 GVariant *
 g_menu_model_get_item_attribute_value (GMenuModel         *model,
                                        gint                item_index,
@@ -440,6 +519,28 @@ g_menu_model_get_item_attribute_value (GMenuModel         *model,
     ->get_item_attribute_value (model, item_index, attribute, expected_type);
 }
 
+/**
+ * g_menu_model_get_item_attribute:
+ * @model: a #GMenuModel
+ * @item_index: the index of the item
+ * @attribute: the attribute to query
+ * @format_string: a #GVariant format string
+ * @...: positional parameters, as per @format_string
+ *
+ * Queries item at position @item_index in @model for the attribute
+ * specified by @attribute.
+ *
+ * If the attribute exists and matches the #GVariantType corresponding
+ * to @format_string then @format_string is used to deconstruct the
+ * value into the positional parameters and %TRUE is returned.
+ *
+ * If the attribute does not exist, or it does exist but has the wrong
+ * type, then the positional parameters are ignored and %FALSE is
+ * returned.
+ *
+ * Returns: %TRUE if the named attribute was found with the expected
+ *          type
+ **/
 gboolean
 g_menu_model_get_item_attribute (GMenuModel  *model,
                                  gint         item_index,
@@ -465,6 +566,18 @@ g_menu_model_get_item_attribute (GMenuModel  *model,
   return TRUE;
 }
 
+/**
+ * g_menu_model_iterate_item_links:
+ * @model: a #GMenuModel
+ * @item_index: the index of the item
+ *
+ * Creates a #GMenuLinkIter to iterate over the links of the item at
+ * position @item_index in @model.
+ *
+ * You must free the iterator with g_object_unref() when you are done.
+ *
+ * Returns: (transfer full): a new #GMenuLinkIter
+ **/
 GMenuLinkIter *
 g_menu_model_iterate_item_links (GMenuModel *model,
                                  gint        item_index)
@@ -473,6 +586,20 @@ g_menu_model_iterate_item_links (GMenuModel *model,
     ->iterate_item_links (model, item_index);
 }
 
+/**
+ * g_menu_model_get_item_link:
+ * @model: a #GMenuModel
+ * @item_index: the index of the item
+ * @link: the link to query
+ *
+ * Queries the item at position @item_index in @model for the link
+ * specified by @link.
+ *
+ * If the link exists, the linked #GMenuModel is returned.  If the link
+ * does not exist, %NULL is returned.
+ *
+ * Returns: (transfer full): the linked #GMenuModel, or %NULL
+ **/
 GMenuModel *
 g_menu_model_get_item_link (GMenuModel *model,
                             gint        item_index,
@@ -482,6 +609,29 @@ g_menu_model_get_item_link (GMenuModel *model,
     ->get_item_link (model, item_index, link);
 }
 
+/**
+ * g_menu_model_items_changed:
+ * @model: a #GMenuModel
+ * @position: the position of the change
+ * @removed: the number of items removed
+ * @added: the number of items added
+ *
+ * Requests emission of the "items-changed" signal on @model.
+ *
+ * This function should never be called except by #GMenuModel
+ * subclasses.  Any other calls to this function will very likely lead
+ * to a violation of the interface of the model.
+ *
+ * The implementation should update its internal representation of the
+ * menu before emitting the signal.  The implementation should further
+ * expect to receive queries about the new state of the menu (and
+ * particularly added menu items) while signal handlers are running.
+ *
+ * The implementation must dispatch this call directly from a mainloop
+ * entry and not in response to calls -- particularly those from the
+ * #GMenuModel API.  Said another way: the menu must not change while
+ * user code is running without returning to the mainloop.
+ **/
 void
 g_menu_model_items_changed (GMenuModel *model,
                             gint        position,
@@ -500,6 +650,31 @@ struct _GMenuAttributeIterPrivate
   gboolean valid;
 };
 
+/**
+ * g_menu_attribute_iter_get_next:
+ * @iter: a #GMenuLinkIter
+ * @name: (out) (allow-none) (transfer none): the name of the attribute
+ * @value: (out) (allow-none) (transfer full): the attribute value
+ *
+ * This function combines g_menu_attribute_iter_next() with
+ * g_menu_attribute_iter_get_name() and g_menu_attribute_iter_get_value().
+ *
+ * First the iterator is advanced to the next (possibly first) attribute.
+ * If that fails, then %FALSE is returned and there are no other
+ * effects.
+ *
+ * If successful, @name and @value are set to the name and value of the
+ * attribute that has just been advanced to.  At this point,
+ * g_menu_item_get_name() and g_menu_item_get_value() will return the
+ * same values again.
+ *
+ * The value returned in @name remains valid for as long as the iterator
+ * remains at the current position.  The value returned in @value must
+ * be unreffed using g_variant_unref() when it is no longer in use.
+ *
+ * Returns: %TRUE on success, or %FALSE if there is no additional
+ *          attribute
+ **/
 gboolean
 g_menu_attribute_iter_get_next (GMenuAttributeIter  *iter,
                                 const gchar        **name,
@@ -520,12 +695,42 @@ g_menu_attribute_iter_get_next (GMenuAttributeIter  *iter,
   return iter->priv->valid;
 }
 
+/**
+ * g_menu_attribute_iter_next:
+ * @iter: a #GMenuLinkIter
+ *
+ * Attempts to advance the iterator to the next (possibly first)
+ * attribute.
+ *
+ * %TRUE is returned on success, or %FALSE if there are no more
+ * attributes.
+ *
+ * You must call this function when you first acquire the iterator to
+ * advance it to the first attribute (and determine if the first
+ * attribute exists at all).
+ *
+ * Returns: %TRUE on success, or %FALSE when there are no more attributes
+ **/
 gboolean
 g_menu_attribute_iter_next (GMenuAttributeIter *iter)
 {
   return g_menu_attribute_iter_get_next (iter, NULL, NULL);
 }
 
+/**
+ * g_menu_attribute_iter_get_name:
+ * @iter: a #GMenuLinkIter
+ *
+ * Gets the name of the attribute at the current iterator position, as a
+ * string.
+ *
+ * The iterator is not advanced.
+ *
+ * The string is owned by the iterator and remains valid for as long as
+ * the iterator is at the current position.
+ *
+ * Returns: (transfer none): the name of the attribute
+ **/
 const gchar *
 g_menu_attribute_iter_get_name (GMenuAttributeIter *iter)
 {
@@ -534,6 +739,16 @@ g_menu_attribute_iter_get_name (GMenuAttributeIter *iter)
   return iter->priv->name;
 }
 
+/**
+ * g_menu_attribute_iter_get_value:
+ * @iter: a #GMenuLinkIter
+ *
+ * Gets the value of the attribute at the current iterator position.
+ *
+ * The iterator is not advanced.
+ *
+ * Returns: (transfer full): the value of the current attribute
+ **/
 GVariant *
 g_menu_attribute_iter_get_value (GMenuAttributeIter *iter)
 {
@@ -579,6 +794,29 @@ struct _GMenuLinkIterPrivate
   gboolean valid;
 };
 
+/**
+ * g_menu_link_iter_get_next:
+ * @iter: a #GMenuLinkIter
+ * @name: (out) (allow-none) (transfer none): the name of the link
+ * @value: (out) (allow-none) (transfer full): the linked #GMenuModel
+ *
+ * This function combines g_menu_link_iter_next() with
+ * g_menu_link_iter_get_name() and g_menu_link_iter_get_value().
+ *
+ * First the iterator is advanced to the next (possibly first) link.  If
+ * that fails, then %FALSE is returned and there are no other effects.
+ *
+ * If successful, @name and @value are set to the name and #GMenuModel
+ * of the link that has just been advanced to.  At this point,
+ * g_menu_item_get_name() and g_menu_item_get_value() will return the
+ * same values again.
+ *
+ * The value returned in @name remains valid for as long as the iterator
+ * remains at the current position.  The value returned in @value must
+ * be unreffed using g_object_unref() when it is no longer in use.
+ *
+ * Returns: %TRUE on success, or %FALSE if there is no additional link
+ **/
 gboolean
 g_menu_link_iter_get_next (GMenuLinkIter  *iter,
                            const gchar   **name,
@@ -599,12 +837,41 @@ g_menu_link_iter_get_next (GMenuLinkIter  *iter,
   return iter->priv->valid;
 }
 
+/**
+ * g_menu_link_iter_next:
+ * @iter: a #GMenuLinkIter
+ *
+ * Attempts to advance the iterator to the next (possibly first)
+ * link.
+ *
+ * %TRUE is returned on success, or %FALSE if there are no more links.
+ *
+ * You must call this function when you first acquire the iterator to
+ * advance it to the first link (and determine if the first link exists
+ * at all).
+ *
+ * Returns: %TRUE on success, or %FALSE when there are no more links
+ **/
 gboolean
 g_menu_link_iter_next (GMenuLinkIter *iter)
 {
   return g_menu_link_iter_get_next (iter, NULL, NULL);
 }
 
+/**
+ * g_menu_link_iter_get_name:
+ * @iter: a #GMenuLinkIter
+ *
+ * Gets the name of the link at the current iterator position, as a
+ * string.
+ *
+ * The iterator is not advanced.
+ *
+ * The string is owned by the iterator and remains valid for as long as
+ * the iterator is at the current position.
+ *
+ * Returns: (transfer none): the name of the link
+ **/
 const gchar *
 g_menu_link_iter_get_name (GMenuLinkIter *iter)
 {
@@ -613,6 +880,16 @@ g_menu_link_iter_get_name (GMenuLinkIter *iter)
   return iter->priv->name;
 }
 
+/**
+ * g_menu_link_iter_get_value:
+ * @iter: a #GMenuLinkIter
+ *
+ * Gets the linked #GMenuModel at the current iterator position.
+ *
+ * The iterator is not advanced.
+ *
+ * Returns: (transfer full): the #GMenuModel that is linked to
+ **/
 GMenuModel *
 g_menu_link_iter_get_value (GMenuLinkIter *iter)
 {
@@ -649,12 +926,42 @@ g_menu_link_iter_class_init (GMenuLinkIterClass *class)
   g_type_class_add_private (class, sizeof (GMenuLinkIterPrivate));
 }
 
+/**
+ * g_menu_model_item_iterate_attributes:
+ * @item: a #GMenuModelItem
+ *
+ * Creates a #GMenuLinkIter to iterate over the links of @item.
+ *
+ * You must free the iterator with g_object_unref() when you are done.
+ *
+ * Returns: (transfer full): a new #GMenuLinkIter
+ **/
 GMenuAttributeIter *
 g_menu_model_item_iterate_attributes (GMenuModelItem *item)
 {
   return g_menu_model_iterate_item_attributes (item->model, item->position);
 }
 
+/**
+ * g_menu_model_item_get_attribute_value:
+ * @item: a #GMenuModelItem
+ * @attribute: the attribute to query
+ * @expected_type: (allow-none): the expected type of the attribute, or
+ *                               %NULL
+ *
+ * Queries @item for the attribute specified by @attribute.
+ *
+ * If @expected_type is non-%NULL then it specifies the expected type of
+ * the attribute.  If it is %NULL then any type will be accepted.
+ *
+ * If the attribute exists and matches @expected_type (or if the
+ * expected type is unspecified) then the value is returned.
+ *
+ * If the attribute does not exist, or does not match the expected type
+ * then %NULL is returned.
+ *
+ * Returns: (transfer full): the value of the attribute
+ **/
 GVariant *
 g_menu_model_item_get_attribute_value (GMenuModelItem     *item,
                                        GQuark              attribute,
@@ -663,6 +970,26 @@ g_menu_model_item_get_attribute_value (GMenuModelItem     *item,
   return g_menu_model_get_item_attribute_value (item->model, item->position, attribute, expected_type);
 }
 
+/**
+ * g_menu_model_item_get_attribute:
+ * @item: a #GMenuModelItem
+ * @attribute: the attribute to query
+ * @format_string: a #GVariant format string
+ * @...: positional parameters, as per @format_string
+ *
+ * Queries @item for the attribute specified by @attribute.
+ *
+ * If the attribute exists and matches the #GVariantType corresponding
+ * to @format_string then @format_string is used to deconstruct the
+ * value into the positional parameters and %TRUE is returned.
+ *
+ * If the attribute does not exist, or it does exist but has the wrong
+ * type, then the positional parameters are ignored and %FALSE is
+ * returned.
+ *
+ * Returns: %TRUE if the named attribute was found with the expected
+ *          type
+ **/
 gboolean
 g_menu_model_item_get_attribute (GMenuModelItem *item,
                                  GQuark          attribute,
@@ -687,12 +1014,34 @@ g_menu_model_item_get_attribute (GMenuModelItem *item,
   return TRUE;
 }
 
+/**
+ * g_menu_model_item_iterate_links:
+ * @item: a #GMenuModelItem
+ *
+ * Creates a #GMenuLinkIter to iterate over the links of @item.
+ *
+ * You must free the iterator with g_object_unref() when you are done.
+ *
+ * Returns: (transfer full): a new #GMenuLinkIter
+ **/
 GMenuLinkIter *
 g_menu_model_item_iterate_links (GMenuModelItem *item)
 {
   return g_menu_model_iterate_item_links (item->model, item->position);
 }
 
+/**
+ * g_menu_model_item_get_link:
+ * @item: a #GMenuModelItem
+ * @link: the link to query
+ *
+ * Queries @item for the link specified by @link.
+ *
+ * If the link exists, the linked #GMenuModel is returned.  If the link
+ * does not exist, %NULL is returned.
+ *
+ * Returns: (transfer full): the linked #GMenuModel, or %NULL
+ **/
 GMenuModel *
 g_menu_model_item_get_link (GMenuModelItem *item,
                             GQuark          link)