Some documentation tweaks

Add links to the D-Bus docs in some places, and various
other additions.

docs/reference/gio/overview.xml

@@ -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>

gio/gdbusaddress.c

@@ -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>.
  */
 
 /* ---------------------------------------------------------------------------------------------------- */

gio/gdbusconnection.c

@@ -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>
  *

gio/gdbusintrospection.c

@@ -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>.
  */
 
 /* ---------------------------------------------------------------------------------------------------- */

gio/gdbusmethodinvocation.c

@@ -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

gio/gdbusnameowning.c

@@ -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

gio/gdbusproxywatching.c

@@ -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