Add return_if_fail and docs for D-Bus address routines

5 files changed, 75 insertions, 16 deletions

diff --git a/docs/reference/gdbus/gdbus-standalone-sections.txt b/docs/reference/gdbus/gdbus-standalone-sections.txt
index fff2306..e98b4b9 100644
--- a/docs/reference/gdbus/gdbus-standalone-sections.txt
+++ b/docs/reference/gdbus/gdbus-standalone-sections.txt
@@ -1,9 +1,9 @@
 <SECTION>
 <FILE>gdbusaddress</FILE>
-g_dbus_address_get_for_bus
 g_dbus_address_get_stream
 g_dbus_address_get_stream_finish
 g_dbus_address_get_stream_sync
+g_dbus_address_get_for_bus_sync
 </SECTION>
 
 <SECTION>
diff --git a/gdbus/gdbusaddress.c b/gdbus/gdbusaddress.c
index fa6a64b..4ceb8e0 100644
--- a/gdbus/gdbusaddress.c
+++ b/gdbus/gdbusaddress.c
@@ -37,10 +37,10 @@
 /**
  * SECTION:gdbusaddress
  * @title: D-Bus Addresses
- * @short_description: Potential connection endpoints
+ * @short_description: D-Bus connection endpoints
  * @include: gdbus/gdbus.h
  *
- * TODO
+ * Routines for working with D-Bus addresses.
  */
 
 /* ---------------------------------------------------------------------------------------------------- */
@@ -344,6 +344,24 @@ get_stream_thread_func (GSimpleAsyncResult *res,
     }
 }
 
+/**
+ * g_dbus_address_get_stream:
+ * @address: A valid D-Bus address.
+ * @cancellable: A #GCancellable or %NULL.
+ * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
+ * @user_data: Data to pass to @callback.
+ *
+ * Asynchronously connects to an endpoint specified by @address and
+ * sets up the connection so it is in a state to run the D-Bus
+ * authentication conversation.
+ *
+ * When the operation is finished, @callback will be invoked. You can
+ * then call g_dbus_address_get_stream_finish() to get the result of
+ * the operation.
+ *
+ * This is an asynchronous failable function. See
+ * g_dbus_address_get_stream_sync() for the synchronous version.
+ */
 void
 g_dbus_address_get_stream (const gchar         *address,
                            GCancellable        *cancellable,
@@ -353,6 +371,8 @@ g_dbus_address_get_stream (const gchar         *address,
   GSimpleAsyncResult *res;
   GetStreamData *data;
 
+  g_return_if_fail (address != NULL);
+
   res = g_simple_async_result_new (NULL,
                                    callback,
                                    user_data,
@@ -369,6 +389,16 @@ g_dbus_address_get_stream (const gchar         *address,
   g_object_unref (res);
 }
 
+/**
+ * g_dbus_address_get_stream_finish:
+ * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream().
+ * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
+ * @error: Return location for error or %NULL.
+ *
+ * Finishes an operation started with g_dbus_address_get_stream().
+ *
+ * Returns: A #GIOStream or %NULL if @error is set.
+ */
 GIOStream *
 g_dbus_address_get_stream_finish (GAsyncResult        *res,
                                   gchar              **out_guid,
@@ -378,6 +408,9 @@ g_dbus_address_get_stream_finish (GAsyncResult        *res,
   GetStreamData *data;
   GIOStream *ret;
 
+  g_return_val_if_fail (G_IS_ASYNC_RESULT (res), NULL);
+  g_return_val_if_fail (error == NULL || *error == NULL, NULL);
+
   g_warn_if_fail (g_simple_async_result_get_source_tag (simple) == g_dbus_address_get_stream);
 
   ret = NULL;
@@ -394,6 +427,23 @@ g_dbus_address_get_stream_finish (GAsyncResult        *res,
   return ret;
 }
 
+/**
+ * g_dbus_address_get_stream_sync:
+ * @address: A valid D-Bus address.
+ * @cancellable: A #GCancellable or %NULL.
+ * @out_guid: %NULL or return location to store the GUID extracted from @address, if any.
+ * @cancellable: A #GCancellable or %NULL.
+ * @error: Return location for error or %NULL.
+ *
+ * Synchronously connects to an endpoint specified by @address and
+ * sets up the connection so it is in a state to run the D-Bus
+ * authentication conversation.
+ *
+ * This is a synchronous failable function. See
+ * g_dbus_address_get_stream() for the asynchronous version.
+ *
+ * Returns: A #GIOStream or %NULL if @error is set.
+ */
 GIOStream *
 g_dbus_address_get_stream_sync (const gchar         *address,
                                 gchar              **out_guid,
@@ -405,6 +455,9 @@ g_dbus_address_get_stream_sync (const gchar         *address,
   guint n;
   GError *last_error;
 
+  g_return_val_if_fail (address != NULL, NULL);
+  g_return_val_if_fail (error == NULL || *error == NULL, NULL);
+
   ret = NULL;
   last_error = NULL;
 
@@ -581,22 +634,27 @@ get_session_address_platform_specific (void)
 /* ---------------------------------------------------------------------------------------------------- */
 
 /**
- * g_dbus_address_get_for_bus:
- * @bus_type: A #GDBusType.
+ * g_dbus_address_get_for_bus_sync:
+ * @bus_type: A #GBusType.
+ * @cancellable: A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
- * Looks up the D-Bus address for the well-known message bus instance
- * specified by @bus_type.
+ * Synchronously looks up the D-Bus address for the well-known message
+ * bus instance specified by @bus_type. This may involve using various
+ * platform specific mechanisms.
  *
  * Returns: A valid D-Bus address string for @bus_type or %NULL if @error is set.
  */
 gchar *
-g_dbus_address_get_for_bus (GBusType   bus_type,
-                            GError   **error)
+g_dbus_address_get_for_bus_sync (GBusType       bus_type,
+                                 GCancellable  *cancellable,
+                                 GError       **error)
 {
   gchar *ret;
   const gchar *starter_bus;
 
+  g_return_val_if_fail (error == NULL || *error == NULL, NULL);
+
   ret = NULL;
 
   switch (bus_type)
@@ -628,12 +686,12 @@ g_dbus_address_get_for_bus (GBusType   bus_type,
       starter_bus = g_getenv ("DBUS_STARTER_BUS_TYPE");
       if (g_strcmp0 (starter_bus, "session") == 0)
         {
-          ret = g_dbus_address_get_for_bus (G_BUS_TYPE_SESSION, error);
+          ret = g_dbus_address_get_for_bus_sync (G_BUS_TYPE_SESSION, cancellable, error);
           goto out;
         }
       else if (g_strcmp0 (starter_bus, "system") == 0)
         {
-          ret = g_dbus_address_get_for_bus (G_BUS_TYPE_SYSTEM, error);
+          ret = g_dbus_address_get_for_bus_sync (G_BUS_TYPE_SYSTEM, cancellable, error);
           goto out;
         }
       else
diff --git a/gdbus/gdbusaddress.h b/gdbus/gdbusaddress.h
index 51cddb7..bdb9b5d 100644
--- a/gdbus/gdbusaddress.h
+++ b/gdbus/gdbusaddress.h
@@ -31,9 +31,6 @@
 
 G_BEGIN_DECLS
 
-gchar               *g_dbus_address_get_for_bus       (GBusType              bus_type,
-                                                       GError              **error);
-
 void                 g_dbus_address_get_stream        (const gchar          *address,
                                                        GCancellable         *cancellable,
                                                        GAsyncReadyCallback   callback,
@@ -48,6 +45,10 @@ GIOStream           *g_dbus_address_get_stream_sync   (const gchar          *add
                                                        GCancellable         *cancellable,
                                                        GError              **error);
 
+gchar               *g_dbus_address_get_for_bus_sync  (GBusType              bus_type,
+                                                       GCancellable  *cancellable,
+                                                       GError              **error);
+
 G_END_DECLS
 
 #endif /* __G_DBUS_ADDRESS_H__ */
diff --git a/gdbus/gdbusconnection.c b/gdbus/gdbusconnection.c
index 4d06d7a..0d2e6ba 100644
--- a/gdbus/gdbusconnection.c
+++ b/gdbus/gdbusconnection.c
@@ -4819,7 +4819,7 @@ get_uninitialized_connection (GBusType            bus_type,
   if (*singleton == NULL)
     {
       gchar *address;
-      address = g_dbus_address_get_for_bus (bus_type, error);
+      address = g_dbus_address_get_for_bus_sync (bus_type, cancellable, error);
       if (address == NULL)
         goto out;
       ret = *singleton = g_object_new (G_TYPE_DBUS_CONNECTION,
diff --git a/gdbus/tests/tests.c b/gdbus/tests/tests.c
index 512ffdd..46f3b3a 100644
--- a/gdbus/tests/tests.c
+++ b/gdbus/tests/tests.c
@@ -140,7 +140,7 @@ _g_bus_get_priv (GBusType            bus_type,
 
   ret = NULL;
 
-  address = g_dbus_address_get_for_bus (bus_type, error);
+  address = g_dbus_address_get_for_bus_sync (bus_type, cancellable, error);
   if (address == NULL)
     goto out;