GDBusConnection: document use while uninitialized as undefined behaviour

Bug: https://bugzilla.gnome.org/show_bug.cgi?id=661689
Bug: https://bugzilla.gnome.org/show_bug.cgi?id=662208
Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Reviewed-by: David Zeuthen <davidz@redhat.com>

diff --git a/gio/gdbusconnection.c b/gio/gdbusconnection.c
index 3bf6048..0b80020 100644 (file)
--- a/gio/gdbusconnection.c
+++ b/gio/gdbusconnection.c
@@ -148,6 +148,22 @@
  * an D-Bus client, it is often easier to use the g_bus_own_name(),
  * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs.
  *
+ * Most of the ways to obtain a #GDBusConnection automatically initialize it
+ * (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and
+ * g_bus_get(), and the synchronous versions of those methods, give you an
+ * initialized connection. Language bindings for GIO should use
+ * g_initable_new() or g_async_initable_new(), which also initialize the
+ * connection.
+ *
+ * If you construct an uninitialized #GDBusConnection, such as via
+ * g_object_new(), you must initialize it via g_initable_init() or
+ * g_async_initable_init() before using its methods or properties. Calling
+ * methods or accessing properties on a #GDBusConnection that has not completed
+ * initialization successfully is considered to be invalid, and leads to
+ * undefined behaviour. In particular, if initialization fails with a #GError,
+ * the only valid thing you can do with that #GDBusConnection is to free it
+ * with g_object_unref().
+ *
  * <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>
  *
  * <example id="gdbus-subtree-server"><title>D-Bus subtree example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-subtree.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>