[glib/wip/menus: 24/33] Fill in missing docs

[Ryan Lortie <ryanl src gnome org>]

commit 6bb6c353c5c32737fc4b8feb199ab2a3713fc623
Author: Ryan Lortie <desrt desrt ca>
Date:   Mon Jul 11 03:26:33 2011 +0200

    Fill in missing docs

 gio/gmenu.c      |   14 ++++++++
 gio/gmenumodel.c |   88 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 101 insertions(+), 1 deletions(-)
---
diff --git a/gio/gmenu.c b/gio/gmenu.c
index c336170..3190fc4 100644
--- a/gio/gmenu.c
+++ b/gio/gmenu.c
@@ -24,6 +24,20 @@
  * items (avoiding #GMenuItem) for the common cases.
  **/
 
+/**
+ * GMenu:
+ *
+ * #GMenu is an opaque structure type.  You must access it using the
+ * functions below.
+ **/
+
+/**
+ * GMenuItem:
+ *
+ * #GMenuItem is an opaque structure type.  You must access it using the
+ * functions below.
+ **/
+
 struct _GMenuItem
 {
   GObject parent_instance;
diff --git a/gio/gmenumodel.c b/gio/gmenumodel.c
index ac11333..4391135 100644
--- a/gio/gmenumodel.c
+++ b/gio/gmenumodel.c
@@ -16,6 +16,35 @@
  * menu items.
  **/
 
+/**
+ * GMenuModel:
+ *
+ * #GMenuModel is an opaque structure type.  You must access it using the
+ * functions below.
+ **/
+
+/**
+ * GMenuAttributeIter:
+ *
+ * #GMenuAttributeIter is an opaque structure type.  You must access it
+ * using the functions below.
+ **/
+
+/**
+ * GMenuLinkIter:
+ *
+ * #GMenuLinkIter is an opaque structure type.  You must access it using
+ * the functions below.
+ **/
+
+/**
+ * GMenuModelItem:
+ *
+ * #GMenuModelItem is a structure type that is intended to be stack
+ * allocated.  You can initialise it using g_menu_model_get_item().  The
+ * structure fields should be considered private and subject to change.
+ **/
+
 typedef struct
 {
   GMenuLinkIter parent_instance;
@@ -196,10 +225,39 @@ guint g_menu_model_items_changed_signal;
     return quark;                                       \
   }
 
+/**
+ * G_MENU_ATTRIBUTE_ACTION:
+ *
+ * The "action" attribute.
+ **/
 MAKE_QUARK(action)
+
+/**
+ * G_MENU_ATTRIBUTE_TARGET:
+ *
+ * The "target" attribute.
+ **/
 MAKE_QUARK(target)
+
+/**
+ * G_MENU_ATTRIBUTE_LABEL:
+ *
+ * The "label" attribute.
+ **/
 MAKE_QUARK(label)
+
+/**
+ * G_MENU_LINK_SUBMENU:
+ *
+ * The "submenu" link.
+ **/
 MAKE_QUARK(submenu)
+
+/**
+ * G_MENU_LINK_SECTION:
+ *
+ * The "section" link.
+ **/
 MAKE_QUARK(section)
 
 static GMenuAttributeIter *
@@ -396,6 +454,34 @@ g_menu_model_class_init (GMenuModelClass *class)
   class->iterate_item_links = g_menu_model_real_iterate_item_links;
   class->get_item_link = g_menu_model_real_get_item_link;
 
+  /**
+   * GMenuModel::items-changed:
+   * @model: the #GMenuModel that is changing
+   * @position: the position of the change
+   * @removed: the number of items removed
+   * @added: the number of items added
+   *
+   * Emitted when a change has occured to the menu.
+   *
+   * The only changes that can occur to a menu is that items are removed
+   * or added.  Items may not change (except by being removed and added
+   * back in the same location).  This signal is capable of describing
+   * both of those changes (at the same time).
+   *
+   * The signal means that starting at the index @position, @removed
+   * items were removed and @added items were added in their place.  If
+   * @removed is zero then only items were added.  If @added is zero
+   * then only items were removed.
+   *
+   * As an example, if the menu contains items a, b, c, d (in that
+   * order) and the signal (2, 1, 3) occurs then the new composition of
+   * the menu will be a, b, _, _, _, d (with each _ representing some
+   * new item).
+   *
+   * Signal handlers may query the model (particularly the added items)
+   * and expect to see the results of the modification that is being
+   * reported.  The signal is emitted after the modification.
+   **/
   g_menu_model_items_changed_signal =
     g_signal_new ("items-changed", G_TYPE_MENU_MODEL,
                   G_SIGNAL_RUN_LAST, 0, NULL, NULL,
@@ -616,7 +702,7 @@ g_menu_model_get_item_link (GMenuModel *model,
  * @removed: the number of items removed
  * @added: the number of items added
  *
- * Requests emission of the "items-changed" signal on @model.
+ * Requests emission of the #GMenuMode::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