[glib/gdbus-merge] mention inline use of floating variants

[Matthias Clasen <matthiasc src gnome org>]

commit a63d3bb868b0ee17404cf85520e48d441abbcdf3
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue May 11 23:18:48 2010 -0400

    mention inline use of floating variants

 gio/gdbusconnection.c |   37 ++++++++++++++++++++++++++++++++++++-
 gio/gdbusproxy.c      |   42 ++++++++++++++++++++++++++++++++++++------
 2 files changed, 72 insertions(+), 7 deletions(-)
---
diff --git a/gio/gdbusconnection.c b/gio/gdbusconnection.c
index dd4cbc2..9338867 100644
--- a/gio/gdbusconnection.c
+++ b/gio/gdbusconnection.c
@@ -2365,7 +2365,7 @@ purge_all_filters (GDBusConnection *connection)
 /**
  * g_dbus_connection_remove_filter:
  * @connection: a #GDBusConnection
- * @filer_id: an identifier obtained from g_dbus_connection_add_filter()
+ * @filter_id: an identifier obtained from g_dbus_connection_add_filter()
  *
  * Removes a filter.
  *
@@ -4153,6 +4153,24 @@ add_call_flags (GDBusMessage           *message,
  * not compatible with the D-Bus protocol, the operation fails with
  * %G_IO_ERROR_INVALID_ARGUMENT.
  *
+ * If the @parameters #GVariant is floating, it is consumed. This allows
+ * convenient 'inline' use of g_variant_new(), e.g.:
+ * |[
+ *  g_dbus_connection_call (connection,
+ *                          "org.freedesktop.StringThings",
+ *                          "/org/freedesktop/StringThings",
+ *                          "org.freedesktop.StringThings",
+ *                          "TwoStrings",
+ *                          g_variant_new ("(ss)",
+ *                                         "Thing One",
+ *                                         "Thing Two"),
+ *                          G_DBUS_CALL_FLAGS_NONE,
+ *                          -1,
+ *                          NULL,
+ *                          (GAsyncReadyCallback) two_strings_done,
+ *                          NULL);
+ * ]|
+ *
  * This is an asynchronous method. When the operation is finished, @callback will be invoked
  * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
  * of the thread you are calling this method from. You can then call
@@ -4303,6 +4321,23 @@ g_dbus_connection_call_finish (GDBusConnection  *connection,
  * contains a value not compatible with the D-Bus protocol, the operation
  * fails with %G_IO_ERROR_INVALID_ARGUMENT.
  *
+ * If the @parameters #GVariant is floating, it is consumed.
+ * This allows convenient 'inline' use of g_variant_new(), e.g.:
+ * |[
+ *  g_dbus_connection_call_sync (connection,
+ *                               "org.freedesktop.StringThings",
+ *                               "/org/freedesktop/StringThings",
+ *                               "org.freedesktop.StringThings",
+ *                               "TwoStrings",
+ *                               g_variant_new ("(ss)",
+ *                                              "Thing One",
+ *                                              "Thing Two"),
+ *                               G_DBUS_CALL_FLAGS_NONE,
+ *                               -1,
+ *                               NULL,
+ *                               &amp;error);
+ * ]|
+ *
  * The calling thread is blocked until a reply is received. See
  * g_dbus_connection_call() for the asynchronous version of
  * this method.
diff --git a/gio/gdbusproxy.c b/gio/gdbusproxy.c
index 8309858..9d1d653 100644
--- a/gio/gdbusproxy.c
+++ b/gio/gdbusproxy.c
@@ -1381,12 +1381,28 @@ validate_method_return (const char             *method_name,
  * compatible with the D-Bus protocol, the operation fails with
  * %G_IO_ERROR_INVALID_ARGUMENT.
  *
- * This is an asynchronous method. When the operation is finished, @callback will be invoked
- * in the <link linkend="g-main-context-push-thread-default">thread-default main loop</link>
- * of the thread you are calling this method from. You can then call
- * g_dbus_proxy_call_finish() to get the result of the operation.
- * See g_dbus_proxy_call_sync() for the
- * synchronous version of this method.
+ * If the @parameters #GVariant is floating, it is consumed. This allows
+ * convenient 'inline' use of g_variant_new(), e.g.:
+ * |[
+ *  g_dbus_proxy_call (proxy,
+ *                     "TwoStrings",
+ *                     g_variant_new ("(ss)",
+ *                                    "Thing One",
+ *                                    "Thing Two"),
+ *                     G_DBUS_CALL_FLAGS_NONE,
+ *                     -1,
+ *                     NULL,
+ *                     (GAsyncReadyCallback) two_strings_done,
+ *                     &amp;data);
+ * ]|
+ *
+ * This is an asynchronous method. When the operation is finished,
+ * @callback will be invoked in the
+ * <link linkend="g-main-context-push-thread-default">thread-default
+ * main loop</link> of the thread you are calling this method from.
+ * You can then call g_dbus_proxy_call_finish() to get the result of
+ * the operation. See g_dbus_proxy_call_sync() for the synchronous
+ * version of this method.
  *
  * Since: 2.26
  */
@@ -1517,6 +1533,20 @@ g_dbus_proxy_call_finish (GDBusProxy    *proxy,
  * compatible with the D-Bus protocol, the operation fails with
  * %G_IO_ERROR_INVALID_ARGUMENT.
  *
+ * If the @parameters #GVariant is floating, it is consumed. This allows
+ * convenient 'inline' use of g_variant_new(), e.g.:
+ * |[
+ *  g_dbus_proxy_call_sync (proxy,
+ *                          "TwoStrings",
+ *                          g_variant_new ("(ss)",
+ *                                         "Thing One",
+ *                                         "Thing Two"),
+ *                          G_DBUS_CALL_FLAGS_NONE,
+ *                          -1,
+ *                          NULL,
+ *                          &amp;error);
+ * ]|
+ *
  * The calling thread is blocked until a reply is received. See
  * g_dbus_proxy_call() for the asynchronous version of this
  * method.