[glib] GVariant: be more explicit about adopting and returning floating refs

[Matthias Clasen <matthiasc src gnome org>]

commit c29d800d84d446d3762329815824a8be269c969b
Author: Simon McVittie <simon mcvittie collabora co uk>
Date:   Fri Aug 13 22:42:24 2010 -0400

    GVariant: be more explicit about adopting and returning floating refs
    
    Bug: https://bugzilla.gnome.org/show_bug.cgi?id=622770

 docs/reference/glib/gvariant-varargs.xml |    4 ++-
 glib/gvariant.c                          |   53 +++++++++++++++++++-----------
 2 files changed, 37 insertions(+), 20 deletions(-)
---
diff --git a/docs/reference/glib/gvariant-varargs.xml b/docs/reference/glib/gvariant-varargs.xml
index 2d92af0..c62f61c 100644
--- a/docs/reference/glib/gvariant-varargs.xml
+++ b/docs/reference/glib/gvariant-varargs.xml
@@ -220,7 +220,9 @@
         <link linkend='GVariant'>GVariant</link> should be used in place of the normal C type or types.  For
         <link linkend='g-variant-new'><function>g_variant_new()</function></link> this means that you must pass a
         non-<link linkend='NULL--CAPS'><literal>NULL</literal></link> <code>(<link linkend='GVariant'>GVariant</link>
-        *)</code>.  For <link linkend='g-variant-get'><function>g_variant_get()</function></link> this means that you
+        *)</code>; if it is a floating reference, ownership will be taken, as
+        if by using <link linkend="g-variant-ref-sink"><function>g_variant_ref_sink()</function></link>.
+        For <link linkend='g-variant-get'><function>g_variant_get()</function></link> this means that you
         must pass a pointer to a <code>(<link linkend='GVariant'>GVariant</link> *)</code> for the value to be returned
         by reference or <link linkend='NULL--CAPS'><literal>NULL</literal></link> to ignore the value.  See
         <link linkend='gvariant-format-strings-gvariant'><code>GVariant *</code></link> below.
diff --git a/glib/gvariant.c b/glib/gvariant.c
index ab42d2c..6822a2a 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -316,7 +316,7 @@ g_variant_new_from_trusted (const GVariantType *type,
 /**
  * g_variant_new_boolean:
  * @boolean: a #gboolean value
- * @returns: a new boolean #GVariant instance
+ * @returns: a floating reference to a new boolean #GVariant instance
  *
  * Creates a new boolean #GVariant instance -- either %TRUE or %FALSE.
  *
@@ -374,7 +374,7 @@ g_variant_get_boolean (GVariant *value)
 /**
  * g_variant_new_byte:
  * @byte: a #guint8 value
- * @returns: a new byte #GVariant instance
+ * @returns: a floating reference to a new byte #GVariant instance
  *
  * Creates a new byte #GVariant instance.
  *
@@ -397,7 +397,7 @@ NUMERIC_TYPE (BYTE, byte, guchar)
 /**
  * g_variant_new_int16:
  * @int16: a #gint16 value
- * @returns: a new int16 #GVariant instance
+ * @returns: a floating reference to a new int16 #GVariant instance
  *
  * Creates a new int16 #GVariant instance.
  *
@@ -420,7 +420,7 @@ NUMERIC_TYPE (INT16, int16, gint16)
 /**
  * g_variant_new_uint16:
  * @uint16: a #guint16 value
- * @returns: a new uint16 #GVariant instance
+ * @returns: a floating reference to a new uint16 #GVariant instance
  *
  * Creates a new uint16 #GVariant instance.
  *
@@ -443,7 +443,7 @@ NUMERIC_TYPE (UINT16, uint16, guint16)
 /**
  * g_variant_new_int32:
  * @int32: a #gint32 value
- * @returns: a new int32 #GVariant instance
+ * @returns: a floating reference to a new int32 #GVariant instance
  *
  * Creates a new int32 #GVariant instance.
  *
@@ -466,7 +466,7 @@ NUMERIC_TYPE (INT32, int32, gint32)
 /**
  * g_variant_new_uint32:
  * @uint32: a #guint32 value
- * @returns: a new uint32 #GVariant instance
+ * @returns: a floating reference to a new uint32 #GVariant instance
  *
  * Creates a new uint32 #GVariant instance.
  *
@@ -489,7 +489,7 @@ NUMERIC_TYPE (UINT32, uint32, guint32)
 /**
  * g_variant_new_int64:
  * @int64: a #gint64 value
- * @returns: a new int64 #GVariant instance
+ * @returns: a floating reference to a new int64 #GVariant instance
  *
  * Creates a new int64 #GVariant instance.
  *
@@ -512,7 +512,7 @@ NUMERIC_TYPE (INT64, int64, gint64)
 /**
  * g_variant_new_uint64:
  * @uint64: a #guint64 value
- * @returns: a new uint64 #GVariant instance
+ * @returns: a floating reference to a new uint64 #GVariant instance
  *
  * Creates a new uint64 #GVariant instance.
  *
@@ -535,7 +535,7 @@ NUMERIC_TYPE (UINT64, uint64, guint64)
 /**
  * g_variant_new_handle:
  * @handle: a #gint32 value
- * @returns: a new handle #GVariant instance
+ * @returns: a floating reference to a new handle #GVariant instance
  *
  * Creates a new handle #GVariant instance.
  *
@@ -566,7 +566,7 @@ NUMERIC_TYPE (HANDLE, handle, gint32)
 /**
  * g_variant_new_double:
  * @floating: a #gdouble floating point value
- * @returns: a new double #GVariant instance
+ * @returns: a floating reference to a new double #GVariant instance
  *
  * Creates a new double #GVariant instance.
  *
@@ -591,7 +591,7 @@ NUMERIC_TYPE (DOUBLE, double, gdouble)
  * g_variant_new_maybe:
  * @child_type: (allow-none): the #GVariantType of the child, or %NULL
  * @child: (allow-none): the child value, or %NULL
- * @returns: a new #GVariant maybe instance
+ * @returns: a floating reference to a new #GVariant maybe instance
  *
  * Depending on if @child is %NULL, either wraps @child inside of a
  * maybe container or creates a Nothing instance for the given @type.
@@ -601,6 +601,9 @@ NUMERIC_TYPE (DOUBLE, double, gdouble)
  * If they are both non-%NULL then @child_type must be the type
  * of @child.
  *
+ * If @child is a floating reference (see g_variant_ref_sink()), the new
+ * instance takes ownership of @child.
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -665,11 +668,14 @@ g_variant_get_maybe (GVariant *value)
 /**
  * g_variant_new_variant:
  * @value: a #GVariance instance
- * @returns: a new variant #GVariant instance
+ * @returns: a floating reference to a new variant #GVariant instance
  *
  * Boxes @value.  The result is a #GVariant instance representing a
  * variant containing the original value.
  *
+ * If @child is a floating reference (see g_variant_ref_sink()), the new
+ * instance takes ownership of @child.
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -708,7 +714,7 @@ g_variant_get_variant (GVariant *value)
  * @children: (allow-none) (array length=n_children): an array of
  *            #GVariant pointers, the children
  * @n_children: the length of @children
- * @returns: a new #GVariant array
+ * @returns: a floating reference to a new #GVariant array
  *
  * Creates a new #GVariant array from @children.
  *
@@ -723,6 +729,9 @@ g_variant_get_variant (GVariant *value)
  * All items in the array must have the same type, which must be the
  * same as @child_type, if given.
  *
+ * If the @children are floating references (see g_variant_ref_sink()), the
+ * new instance takes ownership of them as if via g_variant_ref_sink().
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -792,7 +801,7 @@ g_variant_make_tuple_type (GVariant * const *children,
  * g_variant_new_tuple:
  * @children: (array length=n_children): the items to make the tuple out of
  * @n_children: the length of @children
- * @returns: a new #GVariant tuple
+ * @returns: a floating reference to a new #GVariant tuple
  *
  * Creates a new tuple #GVariant out of the items in @children.  The
  * type is determined from the types of @children.  No entry in the
@@ -800,6 +809,9 @@ g_variant_make_tuple_type (GVariant * const *children,
  *
  * If @n_children is 0 then the unit tuple is constructed.
  *
+ * If the @children are floating references (see g_variant_ref_sink()), the
+ * new instance takes ownership of them as if via g_variant_ref_sink().
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -851,13 +863,16 @@ g_variant_make_dict_entry_type (GVariant *key,
  * g_variant_new_dict_entry:
  * @key: a basic #GVariant, the key
  * @value: a #GVariant, the value
- * @returns: a new dictionary entry #GVariant
+ * @returns: a floating reference to a new dictionary entry #GVariant
  *
  * Creates a new dictionary entry #GVariant.  @key and @value must be
  * non-%NULL.
  *
  * @key must be a value of a basic type (ie: not a container).
  *
+ * If the @key or @value are floating references (see g_variant_ref_sink()),
+ * the new instance takes ownership of them as if via g_variant_ref_sink().
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -959,7 +974,7 @@ g_variant_get_fixed_array (GVariant *value,
 /**
  * g_variant_new_string:
  * @string: a normal utf8 nul-terminated string
- * @returns: a new string #GVariant instance
+ * @returns: a floating reference to a new string #GVariant instance
  *
  * Creates a string #GVariant with the contents of @string.
  *
@@ -980,7 +995,7 @@ g_variant_new_string (const gchar *string)
 /**
  * g_variant_new_object_path:
  * @object_path: a normal C nul-terminated string
- * @returns: a new object path #GVariant instance
+ * @returns: a floating reference to a new object path #GVariant instance
  *
  * Creates a DBus object path #GVariant with the contents of @string.
  * @string must be a valid DBus object path.  Use
@@ -1024,7 +1039,7 @@ g_variant_is_object_path (const gchar *string)
 /**
  * g_variant_new_signature:
  * @signature: a normal C nul-terminated string
- * @returns: a new signature #GVariant instance
+ * @returns: a floating reference to a new signature #GVariant instance
  *
  * Creates a DBus type signature #GVariant with the contents of
  * @string.  @string must be a valid DBus type signature.  Use
@@ -1298,7 +1313,7 @@ g_variant_dup_strv (GVariant *value,
 /**
  * g_variant_new_bytestring:
  * @string: a normal nul-terminated string in no particular encoding
- * @returns: a new bytestring #GVariant instance
+ * @returns: a floating reference to a new bytestring #GVariant instance
  *
  * Creates an array-of-bytes #GVariant with the contents of @string.
  * This function is just like g_variant_new_string() except that the