GNOME.org
 

[glib/wip/menus] Documentation additions

commit 367d9a0c5e6a630c3b8387dd48710e846c52e356
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Oct 29 02:41:04 2011 -0400

    Documentation additions

 docs/reference/gio/gio-docs.xml     |    3 ++
 docs/reference/gio/gio-sections.txt |   40 ++++++++++++++++++++++++++++
 gio/gactiongroupexporter.c          |   11 ++++---
 gio/gdbusactiongroup.c              |   50 ++++++++++++++++++++++++++++++-----
 gio/gmenu.c                         |    2 +-
 gio/gmenuexporter.c                 |   11 +++++++
 gio/gmenumarkup.c                   |    4 +-
 gio/gmenumodel.c                    |    2 +-
 gio/gmenuproxy.c                    |   22 +++++++++++++++
 9 files changed, 129 insertions(+), 16 deletions(-)
---
diff --git a/docs/reference/gio/gio-docs.xml b/docs/reference/gio/gio-docs.xml
index f4e40fd..b4e819b 100644
--- a/docs/reference/gio/gio-docs.xml
+++ b/docs/reference/gio/gio-docs.xml
@@ -194,11 +194,14 @@
         <xi:include href="xml/gaction.xml"/>
         <xi:include href="xml/gsimpleaction.xml"/>
         <xi:include href="xml/gactiongroupexporter.xml"/>
+        <xi:include href="xml/gdbusactiongroup.xml"/>
         <xi:include href="xml/gapplication.xml"/>
         <xi:include href="xml/gapplicationcommandline.xml"/>
         <xi:include href="xml/gmenumodel.xml"/>
         <xi:include href="xml/gmenu.xml"/>
         <xi:include href="xml/gmenumarkup.xml"/>
+        <xi:include href="xml/gmenuexporter.xml"/>
+        <xi:include href="xml/gmenuproxy.xml"/>
     </chapter>
     <chapter id="extending">
         <title>Extending GIO</title>
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index 239b2eb..91be3b1 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -2857,6 +2857,26 @@ g_action_group_exporter_query
 </SECTION>
 
 <SECTION>
+<FILE>gdbusactiongroup</FILE>
+GDBusActionGroup
+g_dbus_action_group_new
+g_dbus_action_group_new_finish
+g_dbus_action_group_new_sync
+g_dbus_action_group_inject
+
+<SUBSECTION Standard>
+G_TYPE_DBUS_ACTION_GROUP
+G_DBUS_ACTION_GROUP
+G_DBUS_ACTION_GROUP_CLASS
+G_IS_DBUS_ACTION_GROUP
+G_IS_DBUS_ACTION_GROUP_CLASS
+G_DBUS_ACTION_GROUP_GET_CLASS
+
+<SUBSECTION Private>
+g_dbus_action_group_get_type
+</SECTION>
+
+<SECTION>
 <FILE>gaction</FILE>
 <TITLE>GAction</TITLE>
 GAction
@@ -3443,6 +3463,26 @@ G_DBUS_OBJECT_MANAGER_SERVER_GET_CLASS
 GDBusObjectManagerServerPrivate
 </SECTION>
 
+<SECTION>
+<FILE>gmenuexporter</FILE>
+g_menu_exporter_export
+g_menu_exporter_stop
+g_menu_exporter_query
+</SECTION>
+
+<SECTION>
+<FILE>gmenuproxy</FILE>
+GMenuProxy
+g_menu_proxy_get
+
+<SUBSECTION Standard>
+G_TYPE_MENU_PROXY
+G_MENU_PROXY
+G_IS_MENU_PROXY
+
+<SUBSECTION Private>
+g_menu_proxy_get_type
+</SECTION>
 
 <SECTION>
 <FILE>gmenu</FILE>
diff --git a/gio/gactiongroupexporter.c b/gio/gactiongroupexporter.c
index 0b77e01..060885f 100644
--- a/gio/gactiongroupexporter.c
+++ b/gio/gactiongroupexporter.c
@@ -34,12 +34,13 @@
 /**
  * SECTION:gactiongroupexporter
  * @title: GActionGroup exporter
- * @short_description: Export #GActionGroup<!-- -->s on D-Bus
- * @see_also: #GActionGroup
+ * @short_description: Export GActionGroups on D-Bus
+ * @see_also: #GActionGroup, #GDBusActionGroup
  *
- * #GActionGroupExporter exports a #GActionGroup on D-Bus.  The D-Bus
- * interface that is used is a private implementation detail.
- **/
+ * These functions support exporting a #GActionGroup on D-Bus.
+ * The D-Bus interface that is used is a private implementation
+ * detail.
+ */
 
 G_GNUC_INTERNAL GVariant *
 g_action_group_describe_action (GActionGroup *action_group,
diff --git a/gio/gdbusactiongroup.c b/gio/gdbusactiongroup.c
index 9be9c0b..2557071 100644
--- a/gio/gdbusactiongroup.c
+++ b/gio/gdbusactiongroup.c
@@ -32,11 +32,13 @@
 /**
  * SECTION:gdbusactiongroup
  * @title: GDBusActionGroup
- * @short_description: A dbus GActionGroup implementation
+ * @short_description: A D-Bus GActionGroup implementation
+ * @see_also: <link linkend="gio-GActionGroup-exporter">GActionGroup exporter</link>
  *
- * #GDBusActionGroup is a hash table filled with #ActionInfo objects,
- * implementing the #GActionGroup interface.
- **/
+ * #GDBusActionGroup is an implementation of the #GActionGroup
+ * interface that can be used as a proxy for an action group
+ * that is exported over D-Bus with g_action_group_exporter_export().
+ */
 
 struct _GDBusActionGroup
 {
@@ -458,13 +460,23 @@ g_dbus_action_group_describe_all_done (GObject      *source,
 
 /**
  * g_dbus_action_group_new:
+ * @connection: A #GDBusConnection
+ * @bus_name: the bus name which exports the action group
+ * @object_path: the object path at which the action group is exported
+ * @flags: Flags used when constructing the object
+ * @cancellable: A #GCancellable or %NULL
+ * @callback: Callback function to invoke when the object is ready
+ * @user_data: User data to pass to @callback
  *
  * Creates a new, empty, #GDBusActionGroup.
  *
- * Returns: a new #GDBusActionGroup
+ * This is a failable asynchronous constructor - when the object
+ * is ready, @callback will be invoked and you can use
+ * g_dbus_action_group_new_finish() to get the result.
  *
- * Since: 2.28
- **/
+ * See g_dbus_action_group_new_sync() and for a synchronous version
+ * of this constructor.
+ */
 void
 g_dbus_action_group_new (GDBusConnection       *connection,
                          const gchar           *bus_name,
@@ -504,6 +516,16 @@ g_dbus_action_group_new (GDBusConnection       *connection,
     g_simple_async_result_complete_in_idle (result);
 }
 
+/**
+ * g_dbus_action_group_new_finish:
+ * @res: A #GAsyncResult obtained from the #GAsyncReadyCallback
+ *     function passed to g_dbus_action_group_new()
+ * @error: Return location for error or %NULL
+ *
+ * Finishes creating a #GDBusActionGroup.
+ *
+ * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
+ */
 GDBusActionGroup *
 g_dbus_action_group_new_finish (GAsyncResult  *result,
                                 GError       **error)
@@ -519,6 +541,20 @@ g_dbus_action_group_new_finish (GAsyncResult  *result,
   return g_object_ref (g_simple_async_result_get_op_res_gpointer (simple));
 }
 
+/**
+ * g_dbus_action_group_new_sync:
+ * @connection: A #GDBusConnection
+ * @bus_name: the bus name which exports the action group
+ * @object_path: the object path at which the action group is exported
+ * @flags: Flags used when constructing the object
+ * @cancellable: A #GCancellable or %NULL
+ * @error: Return location for error or %NULL
+ *
+ * This is a synchronous failable constructor. See g_dbus_action_group_new()
+ * and g_dbus_action_group_new_finish() for the asynchronous version.
+ *
+ * Returns: A #GDBusProxy or %NULL if @error is set. Free with g_object_unref().
+ */
 GDBusActionGroup *
 g_dbus_action_group_new_sync (GDBusConnection        *connection,
                               const gchar            *bus_name,
diff --git a/gio/gmenu.c b/gio/gmenu.c
index 501f03b..de9f531 100644
--- a/gio/gmenu.c
+++ b/gio/gmenu.c
@@ -28,7 +28,7 @@
 /**
  * SECTION:gmenu
  * @title: GMenu
- * @short_description: a simple implementation of #GMenuModel
+ * @short_description: A simple implementation of GMenuModel
  *
  * #GMenu is a simple implementation of #GMenuModel.
  *
diff --git a/gio/gmenuexporter.c b/gio/gmenuexporter.c
index c57ec75..0074bad 100644
--- a/gio/gmenuexporter.c
+++ b/gio/gmenuexporter.c
@@ -26,6 +26,17 @@
 #include "gdbusnamewatching.h"
 #include "gdbuserror.h"
 
+/**
+ * SECTION:gmenuexporter
+ * @title: GMenuModel exporter
+ * @short_description: Export GMenuModels on D-Bus
+ * @see_also: #GMenuModel, #GMenuProxy
+ *
+ * These functions support exporting a #GMenuModel on D-Bus.
+ * The D-Bus interface that is used is a private implementation
+ * detail.
+ */
+
 /* {{{1 D-Bus Interface description */
 static GDBusInterfaceInfo *
 org_gtk_Menus_get_interface (void)
diff --git a/gio/gmenumarkup.c b/gio/gmenumarkup.c
index 14605bf..7c97db7 100644
--- a/gio/gmenumarkup.c
+++ b/gio/gmenumarkup.c
@@ -26,11 +26,11 @@
 /**
  * SECTION:gmenumarkup
  * @title: GMenu Markup
- * @short_description: parsing and printing #GMenuModel XML
+ * @short_description: parsing and printing GMenuModel XML
  *
  * There is a standard XML format for #GMenuModel that will be
  * documented here.
- **/
+ */
 
 struct frame
 {
diff --git a/gio/gmenumodel.c b/gio/gmenumodel.c
index a848cb0..690079b 100644
--- a/gio/gmenumodel.c
+++ b/gio/gmenumodel.c
@@ -24,7 +24,7 @@
 /**
  * SECTION:gmenumodel
  * @title: GMenuModel
- * @short_description: an interface representing the contents of a menu
+ * @short_description: An abstract class representing the contents of a menu
  *
  * #GMenuModel represents the contents of a menu -- an ordered list of
  * menu items.
diff --git a/gio/gmenuproxy.c b/gio/gmenuproxy.c
index 5288f03..18d4285 100644
--- a/gio/gmenuproxy.c
+++ b/gio/gmenuproxy.c
@@ -25,6 +25,17 @@
 
 /* Prelude {{{1 */
 
+/**
+ * SECTION:gmenuproxy
+ * @title: GMenuProxy
+ * @short_description: A D-Bus GMenuModel implementation
+ * @see_also: <link linkend="gio-GMenuModel-exporter">GMenuModel Exporter</link>
+ *
+ * #GMenuProxy is an implementation of #GMenuModel that can be used
+ * as a proxy for a menu model that is exported over D-Bus with
+ * g_menu_exporter_export().
+ */
+
 /*
  * There are 3 main (quasi-)classes involved here:
  *
@@ -821,6 +832,17 @@ g_menu_proxy_get_from_group (GMenuProxyGroup *group,
   return proxy;
 }
 
+/**
+ * g_menu_proxy_get:
+ * @connection: a #GDBusConnection
+ * @bus_name: the bus name which exports the menu model
+ * @object_path: the object path at which the menu model is exported
+ *
+ * Obtains a #GMenuProxy for the menu model which is exported
+ * at the given @bus_name and @object_path.
+ *
+ * Returns: (transfer full): a #GMenuProxy object. Free with g_object_unref().
+ */
 GMenuProxy *
 g_menu_proxy_get (GDBusConnection *connection,
                   const gchar     *bus_name,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]