[glib] GDBusInterfaceVTable: clarify memory handling for the method() virtual function

[Owen Taylor <otaylor src gnome org>]

commit 66fc112c742f56f85fc34b458325e87df4cd78d0
Author: Owen W. Taylor <otaylor fishsoup net>
Date:   Thu Oct 9 14:40:45 2014 -0400

    GDBusInterfaceVTable: clarify memory handling for the method() virtual function
    
    There are two consistent interpretations that could be taken for memory
    handling of the 'invocation' parameter passed to the method_call() virtual
    function of GDBusInterfaceVTable
    
     - A reference is passed (transfer full) to the method_call() virtual function,
       and that reference is then passed (transfer full) to the return_value/error
       functions on GDBusMethodInvocation.
     - An internal reference is retained from the point where method_call() is called
       until the return_value/error function is called.
    
    Since the return_value/error functions were already marked (transfer full),
    we use the first interpretation, annotate the invocation parameter of
    method call as (transfer full) and describe this in the documentation, along
    with the idea that you are always supposed to call one of the return_value/error
    functions.
    
    See bug 738122 for the leak this caused in GJS.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=738259

 gio/gdbusconnection.h |   12 +++++++++++-
 1 files changed, 11 insertions(+), 1 deletions(-)
---
diff --git a/gio/gdbusconnection.h b/gio/gdbusconnection.h
index ffded9e..ba054db 100644
--- a/gio/gdbusconnection.h
+++ b/gio/gdbusconnection.h
@@ -261,7 +261,7 @@ GVariant *g_dbus_connection_call_with_unix_fd_list_sync       (GDBusConnection
  * @interface_name: The D-Bus interface name the method was invoked on.
  * @method_name: The name of the method that was invoked.
  * @parameters: A #GVariant tuple with parameters.
- * @invocation: A #GDBusMethodInvocation object that can be used to return a value or error.
+ * @invocation: (transfer full): A #GDBusMethodInvocation object that must be used to return a value or 
error.
  * @user_data: The @user_data #gpointer passed to g_dbus_connection_register_object().
  *
  * The type of the @method_call function in #GDBusInterfaceVTable.
@@ -343,6 +343,16 @@ typedef gboolean  (*GDBusInterfaceSetPropertyFunc) (GDBusConnection       *conne
  * function. The D-Bus call will be directed to your @method_call function,
  * with the provided @interface_name set to "org.freedesktop.DBus.Properties".
  *
+ * Ownership of the #GDBusMethodInvocation object passed to the
+ * method_call() function is transferred to your handler; you must
+ * call one of the methods of #GDBusMethodInvocation to return a reply
+ * (possibly empty), or an error. These functions also take ownership
+ * of the passed-in invocation object, so unless the invocation
+ * object has otherwise been referenced, it will be then be freed.
+ * Calling one of these functions may be done within your
+ * method_call() implementation but it also can be done at a later
+ * point to handle the method asynchronously.
+ *
  * The usual checks on the validity of the calls is performed. For
  * `Get` calls, an error is automatically returned if the property does
  * not exist or the permissions do not allow access. The same checks are