[glib/wip/gapplication] Document the dbus interface

[Matthias Clasen <matthiasc src gnome org>]

commit 9a3be570af826255a859af3049b214d521c6a413
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Jun 3 23:05:38 2010 -0400

    Document the dbus interface

 gio/gapplication.c |   72 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 71 insertions(+), 1 deletions(-)
---
diff --git a/gio/gapplication.c b/gio/gapplication.c
index 9d4f0e7..4f85fb1 100644
--- a/gio/gapplication.c
+++ b/gio/gapplication.c
@@ -44,7 +44,7 @@
  *
  * In addition to single-instance-ness, #GApplication provides support
  * for 'actions', which can be presented to the user in a platform-specific
- * way (e.g. Windows jump lists).
+ * way (e.g. Windows 7 jump lists).
  *
  * Before using #GApplication, you must choose an "application identifier".
  * The expected form of an application identifier is very close to that of
@@ -59,6 +59,76 @@
  *   <listitem>Application identifiers must not exceed 255 characters.</listitem>
  * </itemizedlist>
  *
+ * <refsect2><title>D-Bus implementation</title>
+ * <para>
+ * On UNIX systems using D-Bus, #GApplication is implemented by claiming the
+ * application identifier as a bus name on the session bus. The implementation
+ * exports an object at the object path that is created by replacing '.' with
+ * '/' in the application identifier (e.g. the object path for the
+ * application id 'org.gtk.TestApp' is '/org/gtk/TestApp'). The object
+ * implements the org.gtk.Application interface.
+ * </para>
+ * <classsynopsis class="interface">
+ *   <ooclass><interfacename>org.gtk.Application</interfacename></ooclass>
+ *   <methodsynopsis>
+ *     <void/>
+ *     <methodname>Activate</methodname>
+ *     <methodparam><modifier>in</modifier><type>aay</type><parameter>arguments</parameter></methodparam>
+ *     <methodparam><modifier>in</modifier><type>a{sv}</type><parameter>data</parameter></methodparam>
+ *   </methodsynopsis>
+ *   <methodsynopsis>
+ *     <void/>
+ *     <methodname>InvokeAction</methodname>
+ *     <methodparam><modifier>in</modifier><type>s</type><parameter>action</parameter></methodparam>
+ *     <methodparam><modifier>in</modifier><type>u</type><parameter>timestamp</parameter></methodparam>
+ *   </methodsynopsis>
+ *   <methodsynopsis>
+ *     <type>a{s(sb)}</type>
+ *     <methodname>ListActions</methodname>
+ *     <void/>
+ *   </methodsynopsis>
+ *   <methodsynopsis>
+ *     <void/>
+ *     <methodname>Quit</methodname>
+ *     <methodparam><modifier>in</modifier><type>u</type><parameter>timestamp</parameter></methodparam>
+ *   </methodsynopsis>
+ *   <methodsynopsis>
+ *     <modifier>Signal</modifier>
+ *     <void/>
+ *     <methodname>ActionsChanged</methodname>
+ *     <void/>
+ *   </methodsynopsis>
+ * </classsynopsis>
+ * <para>
+ * The <methodname>Activate</methodname> function is called on the existing
+ * application instance when a second instance fails to take the bus name.
+ * @arguments contains the commandline arguments given to the second instance
+ * and @data contains platform-specific additional data, see @GApplicationPlugin.
+ * </para>
+ * <para>
+ * The <methodname>InvokeAction</methodname> function can be called to invoke
+ * one of the actions exported by the application. The @timestamp parameter
+ * should be taken from the user event that triggered the method call (e.g.
+ * a button press event).
+ * </para>
+ * <para>
+ * The <methodname>ListActions</methodname> function returns a dictionary
+ * with the exported actions of the application. The keys of the dictionary
+ * are the action names, and the values are structs containing the description
+ * for the action and a boolean that represents if the action is enabled or not.
+ * </para>
+ * <para>
+ * The <methodname>Quit</methodname> function can be called to terminate
+ * the application. The @timestamp parameter should be taken from the user
+ * event that triggered the method call (e.g. a button press event).
+ * </para>
+ * <para>
+ * The <methodname>ActionsChanged</methodname> signal is emitted when the
+ * exported actions change (i.e. an action is added, removed, enabled,
+ * disabled, or otherwise changed).
+ * </para>
+ * </refsect2>
+ *
  * Since: 2.24
  */