Commit 8315eb77 authored by Matthias Clasen's avatar Matthias Clasen

Some documentation tweaks

Add links to the D-Bus docs in some places, and various
other additions.
parent 9164fd02
......@@ -105,9 +105,9 @@
<listitem><para>network connection stream</para></listitem>
</varlistentry>
</variablelist>
There is support for connecting to D-Bus, sending and receiving
messages, owning and watching bus names, and making objects
available on the bus:
There is support for connecting to <link linkend="http://www.freedesktop.org/wiki/Software/dbus">D-Bus</link>,
sending and receiving messages, owning and watching bus names,
and making objects available on the bus:
<variablelist>
<varlistentry>
<term>GDBusConnection</term>
......
......@@ -44,7 +44,9 @@
* @short_description: D-Bus connection endpoints
* @include: gio/gio.h
*
* Routines for working with D-Bus addresses.
* Routines for working with D-Bus addresses. A D-Bus address is a string
* like "unix:tmpdir=/tmp/my-app-name". The exact format of addresses
* is explained in detail in the <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#addresses">D-Bus specification</link>.
*/
/* ---------------------------------------------------------------------------------------------------- */
......
......@@ -105,14 +105,14 @@
* @short_description: D-Bus Connections
* @include: gio/gio.h
*
* <para><note>
* This class is rarely used directly in D-Bus clients. If you are
* writing an D-Bus client, it is often easier to use the
* g_bus_own_name(), g_bus_watch_name() or g_bus_watch_proxy() APIs.
* </note></para>
*
* The #GDBusConnection type is used for D-Bus connections to remote
* peers such as a message buses.
* peers such as a message buses. It is a low-level API that offers a
* lot of flexibility. For instance, it lets you establish a connection
* over any transport that can by represented as an #GIOStream.
*
* This class is rarely used directly in D-Bus clients. If you are writing
* an D-Bus client, it is often easier to use the g_bus_own_name(),
* g_bus_watch_name() or g_bus_watch_proxy() APIs.
*
* <example id="gdbus-server"><title>D-Bus server example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
*
......
......@@ -37,7 +37,11 @@
* @include: gio/gio.h
*
* Various data structures and convenience routines to parse and
* generate D-Bus introspection XML.
* generate D-Bus introspection XML. Introspection information is
* used when registering objects with g_dbus_connection_register_object().
*
* The format of D-BUs introspection XML is specified in the
* <link linkend="http://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format">D-Bus specification</link>.
*/
/* ---------------------------------------------------------------------------------------------------- */
......
......@@ -43,6 +43,10 @@
* Instances of the #GDBusMethodInvocation class are used when
* handling D-Bus method calls. It provides a way to asynchronously
* return results and errors.
*
* The normal way to obtain a #GDBusMethodInvocation object is to receive
* it as an argument to the handle_method_call() function in a
* #GDBusInterfaceVTable that was passed to g_dbus_connection_register_object().
*/
struct _GDBusMethodInvocationPrivate
......
......@@ -553,8 +553,9 @@ g_bus_own_name_on_connection (GDBusConnection *connection,
* closes, then @name_lost_handler is invoked since it is no
* longer possible for other processes to access the process.
*
* You cannot use g_bus_own_name() several times (unless interleaved
* with calls to g_bus_unown_name()) - only the first call will work.
* You cannot use g_bus_own_name() several times for the same name (unless
* interleaved with calls to g_bus_unown_name()) - only the first call
* will work.
*
* Another guarantee is that invocations of @name_acquired_handler
* and @name_lost_handler are guaranteed to alternate; that
......@@ -562,14 +563,15 @@ g_bus_own_name_on_connection (GDBusConnection *connection,
* guaranteed that the next time one of the handlers is invoked, it
* will be @name_lost_handler. The reverse is also true.
*
* If you plan on exporting objects (using e.g. g_dbus_connection_register_object()), note
* that it is generally too late to export the objects in @name_acquired_handler. Instead,
* you can do this in @bus_acquired_handler since you are guaranteed that this will
* run before @name is requested from the bus.
* If you plan on exporting objects (using e.g.
* g_dbus_connection_register_object()), note that it is generally too late
* to export the objects in @name_acquired_handler. Instead, you can do this
* in @bus_acquired_handler since you are guaranteed that this will run
* before @name is requested from the bus.
*
* This behavior makes it very simple to write applications that wants
* to own names and export objects, see <xref linkend="gdbus-owning-names"/>. Simply
* register objects to be exported in @bus_acquired_handler and
* to own names and export objects, see <xref linkend="gdbus-owning-names"/>.
* Simply register objects to be exported in @bus_acquired_handler and
* unregister the objects (if any) in @name_lost_handler.
*
* Returns: An identifier (never 0) that an be used with
......
......@@ -291,7 +291,7 @@ on_name_vanished (GDBusConnection *connection,
* additional proxies in response to the result of enumeration methods
* on the manager object.
*
* Many of the comment that applies to g_bus_watch_name() also applies
* Many of the comments that apply to g_bus_watch_name() also apply
* here. For example, you are guaranteed that one of the handlers will
* be invoked (on the main thread) after calling this function and
* also that the two handlers alternate. When you are done watching the
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment