[glib/wip/menus] Expand docs

[Matthias Clasen <matthiasc src gnome org>]

commit d6025d720d96548ea99e991de02a878dd4ed52cf
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Oct 29 16:25:20 2011 -0400

    Expand docs
    
    I'm dumping my current understanding of things here, so we can
    hopefully grow useful docs by correcting my misunderstandings.

 gio/gactiongroupexporter.c |    4 +++
 gio/gmenu.c                |    9 ++++--
 gio/gmenuexporter.c        |   57 ++++++++++++++++++++++++++++++++++++++++++++
 gio/gmenumarkup.c          |    9 +++++++
 gio/gmenumodel.c           |   43 +++++++++++++++++++++++++++++++-
 5 files changed, 117 insertions(+), 5 deletions(-)
---
diff --git a/gio/gactiongroupexporter.c b/gio/gactiongroupexporter.c
index 060885f..b1da1af 100644
--- a/gio/gactiongroupexporter.c
+++ b/gio/gactiongroupexporter.c
@@ -40,6 +40,9 @@
  * These functions support exporting a #GActionGroup on D-Bus.
  * The D-Bus interface that is used is a private implementation
  * detail.
+ *
+ * To access an exported #GActionGroup remotely, use
+ * g_dbus_action_group_new() to obtain a #GDBusActionGroup.
  */
 
 G_GNUC_INTERNAL GVariant *
@@ -539,6 +542,7 @@ g_action_group_exporter_export (GDBusConnection  *connection,
 
   return TRUE;
 }
+
 /**
  * g_action_group_exporter_stop:
  * @action_group: a #GActionGroup
diff --git a/gio/gmenu.c b/gio/gmenu.c
index 03614ca..b47fceb 100644
--- a/gio/gmenu.c
+++ b/gio/gmenu.c
@@ -34,9 +34,12 @@
  *
  * 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.
- **/
+ * There are some convenience functions to allow you to directly
+ * add items (avoiding #GMenuItem) for the common cases.
+ *
+ * Often it is more convenient to create a #GMenu from an XML
+ * fragment, using <link linkend="gio-GMenu-Markup">GMenu Markup</link>.
+ */
 
 /**
  * GMenu:
diff --git a/gio/gmenuexporter.c b/gio/gmenuexporter.c
index 0074bad..4c0fa45 100644
--- a/gio/gmenuexporter.c
+++ b/gio/gmenuexporter.c
@@ -35,6 +35,9 @@
  * These functions support exporting a #GMenuModel on D-Bus.
  * The D-Bus interface that is used is a private implementation
  * detail.
+ *
+ * To access an exported #GMenuModel remotely, use
+ * g_menu_proxy_get() to obtain a #GMenuProxy.
  */
 
 /* {{{1 D-Bus Interface description */
@@ -755,6 +758,30 @@ g_menu_exporter_new (GDBusConnection  *connection,
 
 static GHashTable *g_menu_exporter_exported_menus;
 
+/**
+ * g_menu_exporter_export:
+ * @connection: a #GDBusConnection
+ * @object_path: a D-Bus object path
+ * @menu: a #GMenuModel
+ * @error: return location for an error, or %NULL
+ *
+ * Exports @menu on @connection at @object_path.
+ *
+ * The implemented D-Bus API should be considered private.
+ * It is subject to change in the future.
+ *
+ * A given menu model can only be exported on one object path
+ * and an object_path can only have one action group exported
+ * on it.  If either constraint is violated, the export will
+ * fail and %FALSE will be returned (with @error set accordingly).
+ *
+ * Use g_menu_exporter_stop() to stop exporting @menu
+ * or g_menu_exporter_query() to find out if and where a given
+ * menu model is exported.
+ *
+ * Returns: %TRUE if the export is successful, or %FALSE (with
+ *     @error set) in the event of a failure.
+ */
 gboolean
 g_menu_exporter_export (GDBusConnection  *connection,
                         const gchar      *object_path,
@@ -782,6 +809,18 @@ g_menu_exporter_export (GDBusConnection  *connection,
   return TRUE;
 }
 
+/**
+ * g_menu_exporter_stop:
+ * @menu: a #GMenuModel
+ *
+ * Stops the export of @menu.
+ *
+ * This reverses the effect of a previous call to
+ * g_menu_exporter_export() for @menu.
+ *
+ * Returns: %TRUE if an export was stopped or %FALSE
+ *     if @menu was not exported in the first place
+ */
 gboolean
 g_menu_exporter_stop (GMenuModel *menu)
 {
@@ -800,6 +839,24 @@ g_menu_exporter_stop (GMenuModel *menu)
   return TRUE;
 }
 
+/**
+ * g_menu_exporter_query:
+ * @menu: a #GMenuModel
+ * @connection: (out): the #GDBusConnection used for exporting
+ * @object_path: (out): the object path used for exporting
+ *
+ * Queries if and where @menu is exported.
+ *
+ * If @menu is exported, %TRUE is returned. If @connection is
+ * non-%NULL then it is set to the #GDBusConnection used for
+ * the export. If @object_path is non-%NULL then it is set to
+ * the object path.
+ *
+ * If the @menu is not exported, %FALSE is returned and
+ * @connection and @object_path remain unmodified.
+ *
+ * Returns: %TRUE if @menu was exported, else %FALSE
+ */
 gboolean
 g_menu_exporter_query (GMenuModel       *menu,
                        GDBusConnection **connection,
diff --git a/gio/gmenumarkup.c b/gio/gmenumarkup.c
index 7c97db7..bd86526 100644
--- a/gio/gmenumarkup.c
+++ b/gio/gmenumarkup.c
@@ -28,8 +28,17 @@
  * @title: GMenu Markup
  * @short_description: parsing and printing GMenuModel XML
  *
+ * The functions here allow to instantiate #GMenuModels by parsing
+ * fragments of an XML document.
+ *
  * There is a standard XML format for #GMenuModel that will be
  * documented here.
+ *
+ * To serialize a #GMenuModel into an XML fragment, use
+ * g_menu_model_print_string()
+ *
+ * To serialize a #GMenuModel into an XML fragment, use
+ * g_menu_markup_print_string().
  */
 
 struct frame
diff --git a/gio/gmenumodel.c b/gio/gmenumodel.c
index 690079b..faf6d03 100644
--- a/gio/gmenumodel.c
+++ b/gio/gmenumodel.c
@@ -25,10 +25,49 @@
  * SECTION:gmenumodel
  * @title: GMenuModel
  * @short_description: An abstract class representing the contents of a menu
+ * @see_also: #GActionGroup
  *
  * #GMenuModel represents the contents of a menu -- an ordered list of
- * menu items.
- **/
+ * menu items. The items represent actions which can be activated.
+ *
+ * The conceptual model of menus that #GMenuModel uses is hierarchical.
+ * Menus contain items which can be grouped in sections. Items may
+ * have submenus associated with them. Both items and sections usually
+ * 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.
+ *
+ * FIXME: add a picture here
+ *
+ * The motivation for having such an abstract representation of an
+ * applications controls is that modern user interfaces have a tendency
+ * to make them available outside the application. Examples of this
+ * include global menus, jumplists, dash boards, etc. To support such
+ * uses, it is necessary to 'export' information about actions and their
+ * representation in menus, which is exactly what the
+ * <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
+ * and the
+ * <link linkend="gio-GMenuModel-exporter">GMenuModel exporter</link>
+ * do for #GActionGroup and #GMenuModel. The client-side counterparts
+ * to make use of the exported information are #GDBusActionGroup and
+ * #GMenuProxy.
+ *
+ * The concrete representation of #GMenuModel is a list of #GMenuModelItems,
+ * see g_menu_model_get_item() and g_menu_model_get_n_items(). Each
+ * item has attributes and links, see g_menu_model_item_iterate_attributes()
+ * and g_menu_model_item_iterate_links(). Among the attributes are
+ * representation data such as a user-visible label, but also the name
+ * of the associated action, see #G_MENU_ATTRIBUTE_LABEL and
+ * #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_model_item_get_link() or
+ * g_menu_link_iter_get_value().
+ *
+ * FIXME: explain how items are associated with actions.
+ */
 
 /**
  * GMenuModel: