From 0e0554bd62e897f001aaa9388345c1d4e62614af Mon Sep 17 00:00:00 2001
From: Ryan Lortie <desrt@desrt.ca>
Date: Mon, 21 Nov 2011 11:33:05 -0500
Subject: [PATCH] GVariant: drop use of @returns

---
 glib/gvariant-core.c       |  42 ++++---
 glib/gvariant-parser.c     |   6 +-
 glib/gvariant-serialiser.c |   6 +-
 glib/gvariant.c            | 240 ++++++++++++++++++++++++-------------
 glib/gvarianttype.c        |  84 ++++++++-----
 5 files changed, 249 insertions(+), 129 deletions(-)

diff --git a/glib/gvariant-core.c b/glib/gvariant-core.c
index 7e63acb7e..6d1e2b34e 100644
--- a/glib/gvariant-core.c
+++ b/glib/gvariant-core.c
@@ -459,11 +459,12 @@ g_variant_ensure_serialised (GVariant *value)
  * @type: the type of the new instance
  * @serialised: if the instance will be in serialised form
  * @trusted: if the instance will be trusted
- * @returns: a new #GVariant with a floating reference
  *
  * Allocates a #GVariant instance and does some common work (such as
  * looking up and filling in the type info), setting the state field,
  * and setting the ref_count to 1.
+ *
+ * Returns: a new #GVariant with a floating reference
  */
 static GVariant *
 g_variant_alloc (const GVariantType *type,
@@ -489,13 +490,14 @@ g_variant_alloc (const GVariantType *type,
  * @type: a #GVariantType
  * @buffer: a #GBuffer
  * @trusted: if the contents of @buffer are trusted
- * @returns: a new #GVariant with a floating reference
  *
  * Constructs a new serialised-mode #GVariant instance.  This is the
  * inner interface for creation of new serialised values that gets
  * called from various functions in gvariant.c.
  *
  * A reference is taken on @buffer.
+ *
+ * Returns: a new #GVariant with a floating reference
  */
 GVariant *
 g_variant_new_from_buffer (const GVariantType *type,
@@ -540,7 +542,6 @@ g_variant_new_from_buffer (const GVariantType *type,
  * @children: an array of #GVariant pointers.  Consumed.
  * @n_children: the length of @children
  * @trusted: %TRUE if every child in @children in trusted
- * @returns: a new #GVariant with a floating reference
  *
  * Constructs a new tree-mode #GVariant instance.  This is the inner
  * interface for creation of new serialised values that gets called from
@@ -548,6 +549,8 @@ g_variant_new_from_buffer (const GVariantType *type,
  *
  * @children is consumed by this function.  g_free() will be called on
  * it some time later.
+ *
+ * Returns: a new #GVariant with a floating reference
  */
 GVariant *
 g_variant_new_from_children (const GVariantType  *type,
@@ -567,11 +570,12 @@ g_variant_new_from_children (const GVariantType  *type,
 /* < internal >
  * g_variant_get_type_info:
  * @value: a #GVariant
- * @returns: the #GVariantTypeInfo for @value
  *
  * Returns the #GVariantTypeInfo corresponding to the type of @value.  A
  * reference is not added, so the return value is only good for the
  * duration of the life of @value.
+ *
+ * Returns: the #GVariantTypeInfo for @value
  */
 GVariantTypeInfo *
 g_variant_get_type_info (GVariant *value)
@@ -582,7 +586,6 @@ g_variant_get_type_info (GVariant *value)
 /* < internal >
  * g_variant_is_trusted:
  * @value: a #GVariant
- * @returns: if @value is trusted
  *
  * Determines if @value is trusted by #GVariant to contain only
  * fully-valid data.  All values constructed solely via #GVariant APIs
@@ -593,6 +596,8 @@ g_variant_get_type_info (GVariant *value)
  * skipped.  For example, we don't need to check that a string is
  * properly nul-terminated or that an object path is actually a
  * properly-formatted object path.
+ *
+ * Returns: if @value is trusted
  */
 gboolean
 g_variant_is_trusted (GVariant *value)
@@ -637,10 +642,11 @@ g_variant_unref (GVariant *value)
 /**
  * g_variant_ref:
  * @value: a #GVariant
- * @returns: the same @value
  *
  * Increases the reference count of @value.
  *
+ * Returns: the same @value
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -654,7 +660,6 @@ g_variant_ref (GVariant *value)
 /**
  * g_variant_ref_sink:
  * @value: a #GVariant
- * @returns: the same @value
  *
  * #GVariant uses a floating reference count system.  All functions with
  * names starting with <literal>g_variant_new_</literal> return floating
@@ -679,6 +684,8 @@ g_variant_ref (GVariant *value)
  * maintaining normal refcounting semantics in situations where values
  * are not floating.
  *
+ * Returns: the same @value
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -699,7 +706,6 @@ g_variant_ref_sink (GVariant *value)
 /**
  * g_variant_take_ref:
  * @value: a #GVariant
- * @returns: the same @value
  *
  * If @value is floating, sink it.  Otherwise, do nothing.
  *
@@ -733,6 +739,8 @@ g_variant_ref_sink (GVariant *value)
  * be that the floating reference is converted to a hard reference and
  * an additional reference on top of that one is added.  It is best to
  * avoid this situation.
+ *
+ * Returns: the same @value
  **/
 GVariant *
 g_variant_take_ref (GVariant *value)
@@ -747,7 +755,6 @@ g_variant_take_ref (GVariant *value)
 /**
  * g_variant_is_floating:
  * @value: a #GVariant
- * @returns: whether @value is floating
  *
  * Checks whether @value has a floating reference count.
  *
@@ -759,6 +766,8 @@ g_variant_take_ref (GVariant *value)
  * See g_variant_ref_sink() for more information about floating reference
  * counts.
  *
+ * Returns: whether @value is floating
+ *
  * Since: 2.26
  **/
 gboolean
@@ -772,7 +781,6 @@ g_variant_is_floating (GVariant *value)
 /**
  * g_variant_get_size:
  * @value: a #GVariant instance
- * @returns: the serialised size of @value
  *
  * Determines the number of bytes that would be required to store @value
  * with g_variant_store().
@@ -786,6 +794,8 @@ g_variant_is_floating (GVariant *value)
  * operation which is approximately O(n) in the number of values
  * involved.
  *
+ * Returns: the serialised size of @value
+ *
  * Since: 2.24
  **/
 gsize
@@ -801,7 +811,6 @@ g_variant_get_size (GVariant *value)
 /**
  * g_variant_get_data:
  * @value: a #GVariant instance
- * @returns: (transfer none): the serialised form of @value, or %NULL
  *
  * Returns a pointer to the serialised form of a #GVariant instance.
  * The returned data may not be in fully-normalised form if read from an
@@ -829,6 +838,8 @@ g_variant_get_size (GVariant *value)
  * explicitly (by storing the type and/or endianness in addition to the
  * serialised data).
  *
+ * Returns: (transfer none): the serialised form of @value, or %NULL
+ *
  * Since: 2.24
  **/
 gconstpointer
@@ -844,7 +855,6 @@ g_variant_get_data (GVariant *value)
 /**
  * g_variant_n_children:
  * @value: a container #GVariant
- * @returns: the number of children in the container
  *
  * Determines the number of children in a container #GVariant instance.
  * This includes variants, maybes, arrays, tuples and dictionary
@@ -858,6 +868,8 @@ g_variant_get_data (GVariant *value)
  *
  * This function is O(1).
  *
+ * Returns: the number of children in the container
+ *
  * Since: 2.24
  **/
 gsize
@@ -889,7 +901,6 @@ g_variant_n_children (GVariant *value)
  * g_variant_get_child_value:
  * @value: a container #GVariant
  * @index_: the index of the child to fetch
- * @returns: (transfer full): the child at the specified index
  *
  * Reads a child item out of a container #GVariant instance.  This
  * includes variants, maybes, arrays, tuples and dictionary
@@ -904,6 +915,8 @@ g_variant_n_children (GVariant *value)
  *
  * This function is O(1).
  *
+ * Returns: (transfer full): the child at the specified index
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -1000,7 +1013,6 @@ g_variant_store (GVariant *value,
 /**
  * g_variant_is_normal_form:
  * @value: a #GVariant instance
- * @returns: %TRUE if @value is in normal form
  *
  * Checks if @value is in normal form.
  *
@@ -1013,6 +1025,8 @@ g_variant_store (GVariant *value,
  * being trusted.  If the value was already marked as being trusted then
  * this function will immediately return %TRUE.
  *
+ * Returns: %TRUE if @value is in normal form
+ *
  * Since: 2.24
  **/
 gboolean
diff --git a/glib/gvariant-parser.c b/glib/gvariant-parser.c
index dbd7a24bf..c0dc8dac4 100644
--- a/glib/gvariant-parser.c
+++ b/glib/gvariant-parser.c
@@ -2406,7 +2406,6 @@ g_variant_parse (const GVariantType  *type,
  * g_variant_new_parsed_va:
  * @format: a text format #GVariant
  * @app: a pointer to a #va_list
- * @returns: a new, usually floating, #GVariant
  *
  * Parses @format and returns the result.
  *
@@ -2425,6 +2424,8 @@ g_variant_parse (const GVariantType  *type,
  * At this point, the caller will have their own full reference to the
  * result.  This can also be done by adding the result to a container,
  * or by passing it to another g_variant_new() call.
+ *
+ * Returns: a new, usually floating, #GVariant
  **/
 GVariant *
 g_variant_new_parsed_va (const gchar *format,
@@ -2461,7 +2462,6 @@ g_variant_new_parsed_va (const gchar *format,
  * g_variant_new_parsed:
  * @format: a text format #GVariant
  * @...: arguments as per @format
- * @returns: a new floating #GVariant instance
  *
  * Parses @format and returns the result.
  *
@@ -2489,6 +2489,8 @@ g_variant_new_parsed_va (const gchar *format,
  * #GVariant pointer from the argument list.  ie: @format may not solely
  * be anything along the lines of "%*", "%?", "\%r", or anything starting
  * with "%@".
+ *
+ * Returns: a new floating #GVariant instance
  **/
 GVariant *
 g_variant_new_parsed (const gchar *format,
diff --git a/glib/gvariant-serialiser.c b/glib/gvariant-serialiser.c
index 5daf43aa5..f07251176 100644
--- a/glib/gvariant-serialiser.c
+++ b/glib/gvariant-serialiser.c
@@ -1300,11 +1300,12 @@ gvs_variant_is_normal (GVariantSerialised value)
 /* < private >
  * g_variant_serialised_n_children:
  * @serialised: a #GVariantSerialised
- * @returns: the number of children
  *
  * For serialised data that represents a container value (maybes,
  * tuples, arrays, variants), determine how many child items are inside
  * that container.
+ *
+ * Returns: the number of children
  */
 gsize
 g_variant_serialised_n_children (GVariantSerialised serialised)
@@ -1323,7 +1324,6 @@ g_variant_serialised_n_children (GVariantSerialised serialised)
  * g_variant_serialised_get_child:
  * @serialised: a #GVariantSerialised
  * @index_: the index of the child to fetch
- * @returns: a #GVariantSerialised for the child
  *
  * Extracts a child from a serialised data representing a container
  * value.
@@ -1338,6 +1338,8 @@ g_variant_serialised_n_children (GVariantSerialised serialised)
  * item of a variable-sized type is being returned.
  *
  * .data is never non-%NULL if size is 0.
+ *
+ * Returns: a #GVariantSerialised for the child
  */
 GVariantSerialised
 g_variant_serialised_get_child (GVariantSerialised serialised,
diff --git a/glib/gvariant.c b/glib/gvariant.c
index c6932fdf7..859cfbb2f 100644
--- a/glib/gvariant.c
+++ b/glib/gvariant.c
@@ -309,10 +309,11 @@
  * @type: the #GVariantType
  * @data: the data to use
  * @size: the size of @data
- * @returns: a new floating #GVariant
  *
  * Constructs a new trusted #GVariant instance from the provided data.
  * This is used to implement g_variant_new_* for all the basic types.
+ *
+ * Returns: a new floating #GVariant
  */
 static GVariant *
 g_variant_new_from_trusted (const GVariantType *type,
@@ -332,10 +333,11 @@ g_variant_new_from_trusted (const GVariantType *type,
 /**
  * g_variant_new_boolean:
  * @value: a #gboolean value
- * @returns: (transfer none): a floating reference to a new boolean #GVariant instance
  *
  * Creates a new boolean #GVariant instance -- either %TRUE or %FALSE.
  *
+ * Returns: (transfer none): a floating reference to a new boolean #GVariant instance
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -349,13 +351,14 @@ g_variant_new_boolean (gboolean value)
 /**
  * g_variant_get_boolean:
  * @value: a boolean #GVariant instance
- * @returns: %TRUE or %FALSE
  *
  * Returns the boolean value of @value.
  *
  * It is an error to call this function with a @value of any type
  * other than %G_VARIANT_TYPE_BOOLEAN.
  *
+ * Returns: %TRUE or %FALSE
+ *
  * Since: 2.24
  **/
 gboolean
@@ -390,22 +393,24 @@ g_variant_get_boolean (GVariant *value)
 /**
  * g_variant_new_byte:
  * @value: a #guint8 value
- * @returns: (transfer none): a floating reference to a new byte #GVariant instance
  *
  * Creates a new byte #GVariant instance.
  *
+ * Returns: (transfer none): a floating reference to a new byte #GVariant instance
+ *
  * Since: 2.24
  **/
 /**
  * g_variant_get_byte:
  * @value: a byte #GVariant instance
- * @returns: a #guchar
  *
  * Returns the byte value of @value.
  *
  * It is an error to call this function with a @value of any type
  * other than %G_VARIANT_TYPE_BYTE.
  *
+ * Returns: a #guchar
+ *
  * Since: 2.24
  **/
 NUMERIC_TYPE (BYTE, byte, guchar)
@@ -413,22 +418,24 @@ NUMERIC_TYPE (BYTE, byte, guchar)
 /**
  * g_variant_new_int16:
  * @value: a #gint16 value
- * @returns: (transfer none): a floating reference to a new int16 #GVariant instance
  *
  * Creates a new int16 #GVariant instance.
  *
+ * Returns: (transfer none): a floating reference to a new int16 #GVariant instance
+ *
  * Since: 2.24
  **/
 /**
  * g_variant_get_int16:
  * @value: a int16 #GVariant instance
- * @returns: a #gint16
  *
  * Returns the 16-bit signed integer value of @value.
  *
  * It is an error to call this function with a @value of any type
  * other than %G_VARIANT_TYPE_INT16.
  *
+ * Returns: a #gint16
+ *
  * Since: 2.24
  **/
 NUMERIC_TYPE (INT16, int16, gint16)
@@ -436,22 +443,24 @@ NUMERIC_TYPE (INT16, int16, gint16)
 /**
  * g_variant_new_uint16:
  * @value: a #guint16 value
- * @returns: (transfer none): a floating reference to a new uint16 #GVariant instance
  *
  * Creates a new uint16 #GVariant instance.
  *
+ * Returns: (transfer none): a floating reference to a new uint16 #GVariant instance
+ *
  * Since: 2.24
  **/
 /**
  * g_variant_get_uint16:
  * @value: a uint16 #GVariant instance
- * @returns: a #guint16
  *
  * Returns the 16-bit unsigned integer value of @value.
  *
  * It is an error to call this function with a @value of any type
  * other than %G_VARIANT_TYPE_UINT16.
  *
+ * Returns: a #guint16
+ *
  * Since: 2.24
  **/
 NUMERIC_TYPE (UINT16, uint16, guint16)
@@ -459,22 +468,24 @@ NUMERIC_TYPE (UINT16, uint16, guint16)
 /**
  * g_variant_new_int32:
  * @value: a #gint32 value
- * @returns: (transfer none): a floating reference to a new int32 #GVariant instance
  *
  * Creates a new int32 #GVariant instance.
  *
+ * Returns: (transfer none): a floating reference to a new int32 #GVariant instance
+ *
  * Since: 2.24
  **/
 /**
  * g_variant_get_int32:
  * @value: a int32 #GVariant instance
- * @returns: a #gint32
  *
  * Returns the 32-bit signed integer value of @value.
  *
  * It is an error to call this function with a @value of any type
  * other than %G_VARIANT_TYPE_INT32.
  *
+ * Returns: a #gint32
+ *
  * Since: 2.24
  **/
 NUMERIC_TYPE (INT32, int32, gint32)
@@ -482,22 +493,24 @@ NUMERIC_TYPE (INT32, int32, gint32)
 /**
  * g_variant_new_uint32:
  * @value: a #guint32 value
- * @returns: (transfer none): a floating reference to a new uint32 #GVariant instance
  *
  * Creates a new uint32 #GVariant instance.
  *
+ * Returns: (transfer none): a floating reference to a new uint32 #GVariant instance
+ *
  * Since: 2.24
  **/
 /**
  * g_variant_get_uint32:
  * @value: a uint32 #GVariant instance
- * @returns: a #guint32
  *
  * Returns the 32-bit unsigned integer value of @value.
  *
  * It is an error to call this function with a @value of any type
  * other than %G_VARIANT_TYPE_UINT32.
  *
+ * Returns: a #guint32
+ *
  * Since: 2.24
  **/
 NUMERIC_TYPE (UINT32, uint32, guint32)
@@ -505,22 +518,24 @@ NUMERIC_TYPE (UINT32, uint32, guint32)
 /**
  * g_variant_new_int64:
  * @value: a #gint64 value
- * @returns: (transfer none): a floating reference to a new int64 #GVariant instance
  *
  * Creates a new int64 #GVariant instance.
  *
+ * Returns: (transfer none): a floating reference to a new int64 #GVariant instance
+ *
  * Since: 2.24
  **/
 /**
  * g_variant_get_int64:
  * @value: a int64 #GVariant instance
- * @returns: a #gint64
  *
  * Returns the 64-bit signed integer value of @value.
  *
  * It is an error to call this function with a @value of any type
  * other than %G_VARIANT_TYPE_INT64.
  *
+ * Returns: a #gint64
+ *
  * Since: 2.24
  **/
 NUMERIC_TYPE (INT64, int64, gint64)
@@ -528,22 +543,24 @@ NUMERIC_TYPE (INT64, int64, gint64)
 /**
  * g_variant_new_uint64:
  * @value: a #guint64 value
- * @returns: (transfer none): a floating reference to a new uint64 #GVariant instance
  *
  * Creates a new uint64 #GVariant instance.
  *
+ * Returns: (transfer none): a floating reference to a new uint64 #GVariant instance
+ *
  * Since: 2.24
  **/
 /**
  * g_variant_get_uint64:
  * @value: a uint64 #GVariant instance
- * @returns: a #guint64
  *
  * Returns the 64-bit unsigned integer value of @value.
  *
  * It is an error to call this function with a @value of any type
  * other than %G_VARIANT_TYPE_UINT64.
  *
+ * Returns: a #guint64
+ *
  * Since: 2.24
  **/
 NUMERIC_TYPE (UINT64, uint64, guint64)
@@ -551,7 +568,6 @@ NUMERIC_TYPE (UINT64, uint64, guint64)
 /**
  * g_variant_new_handle:
  * @value: a #gint32 value
- * @returns: (transfer none): a floating reference to a new handle #GVariant instance
  *
  * Creates a new handle #GVariant instance.
  *
@@ -559,12 +575,13 @@ NUMERIC_TYPE (UINT64, uint64, guint64)
  * that are sent alongside a D-Bus message.  If you're not interacting
  * with D-Bus, you probably don't need them.
  *
+ * Returns: (transfer none): a floating reference to a new handle #GVariant instance
+ *
  * Since: 2.24
  **/
 /**
  * g_variant_get_handle:
  * @value: a handle #GVariant instance
- * @returns: a #gint32
  *
  * Returns the 32-bit signed integer value of @value.
  *
@@ -575,6 +592,8 @@ NUMERIC_TYPE (UINT64, uint64, guint64)
  * that are sent alongside a D-Bus message.  If you're not interacting
  * with D-Bus, you probably don't need them.
  *
+ * Returns: a #gint32
+ *
  * Since: 2.24
  **/
 NUMERIC_TYPE (HANDLE, handle, gint32)
@@ -582,22 +601,24 @@ NUMERIC_TYPE (HANDLE, handle, gint32)
 /**
  * g_variant_new_double:
  * @value: a #gdouble floating point value
- * @returns: (transfer none): a floating reference to a new double #GVariant instance
  *
  * Creates a new double #GVariant instance.
  *
+ * Returns: (transfer none): a floating reference to a new double #GVariant instance
+ *
  * Since: 2.24
  **/
 /**
  * g_variant_get_double:
  * @value: a double #GVariant instance
- * @returns: a #gdouble
  *
  * Returns the double precision floating point value of @value.
  *
  * It is an error to call this function with a @value of any type
  * other than %G_VARIANT_TYPE_DOUBLE.
  *
+ * Returns: a #gdouble
+ *
  * Since: 2.24
  **/
 NUMERIC_TYPE (DOUBLE, double, gdouble)
@@ -607,7 +628,6 @@ 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: (transfer none): 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.
@@ -620,6 +640,8 @@ NUMERIC_TYPE (DOUBLE, double, gdouble)
  * If @child is a floating reference (see g_variant_ref_sink()), the new
  * instance takes ownership of @child.
  *
+ * Returns: (transfer none): a floating reference to a new #GVariant maybe instance
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -663,11 +685,12 @@ g_variant_new_maybe (const GVariantType *child_type,
 /**
  * g_variant_get_maybe:
  * @value: a maybe-typed value
- * @returns: (allow-none) (transfer full): the contents of @value, or %NULL
  *
  * Given a maybe-typed #GVariant instance, extract its value.  If the
  * value is Nothing, then this function returns %NULL.
  *
+ * Returns: (allow-none) (transfer full): the contents of @value, or %NULL
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -684,7 +707,6 @@ g_variant_get_maybe (GVariant *value)
 /**
  * g_variant_new_variant: (constructor)
  * @value: a #GVariant instance
- * @returns: (transfer none): a floating reference to a new variant #GVariant instance
  *
  * Boxes @value.  The result is a #GVariant instance representing a
  * variant containing the original value.
@@ -692,6 +714,8 @@ g_variant_get_maybe (GVariant *value)
  * If @child is a floating reference (see g_variant_ref_sink()), the new
  * instance takes ownership of @child.
  *
+ * Returns: (transfer none): a floating reference to a new variant #GVariant instance
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -709,11 +733,12 @@ g_variant_new_variant (GVariant *value)
 /**
  * g_variant_get_variant:
  * @value: a variant #GVariant instance
- * @returns: (transfer full): the item contained in the variant
  *
  * Unboxes @value.  The result is the #GVariant instance that was
  * contained in @value.
  *
+ * Returns: (transfer full): the item contained in the variant
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -730,7 +755,6 @@ 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: (transfer none): a floating reference to a new #GVariant array
  *
  * Creates a new #GVariant array from @children.
  *
@@ -748,6 +772,8 @@ g_variant_get_variant (GVariant *value)
  * 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().
  *
+ * Returns: (transfer none): a floating reference to a new #GVariant array
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -817,7 +843,6 @@ 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: (transfer none): 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
@@ -828,6 +853,8 @@ g_variant_make_tuple_type (GVariant * const *children,
  * 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().
  *
+ * Returns: (transfer none): a floating reference to a new #GVariant tuple
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -879,7 +906,6 @@ g_variant_make_dict_entry_type (GVariant *key,
  * g_variant_new_dict_entry: (constructor)
  * @key: a basic #GVariant, the key
  * @value: a #GVariant, the value
- * @returns: (transfer none): 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).
@@ -887,6 +913,8 @@ g_variant_make_dict_entry_type (GVariant *key,
  * 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().
  *
+ * Returns: (transfer none): a floating reference to a new dictionary entry #GVariant
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -1061,8 +1089,6 @@ g_variant_lookup_value (GVariant           *dictionary,
  * @value: a #GVariant array with fixed-sized elements
  * @n_elements: (out): a pointer to the location to store the number of items
  * @element_size: the size of each element
- * @returns: (array length=n_elements) (transfer none): a pointer to
- *           the fixed array
  *
  * Provides access to the serialised data for an array of fixed-sized
  * items.
@@ -1102,6 +1128,9 @@ g_variant_lookup_value (GVariant           *dictionary,
  * @n_elements, which must be non-%NULL is set equal to the number of
  * items in the array.
  *
+ * Returns: (array length=n_elements) (transfer none): a pointer to
+ *          the fixed array
+ *
  * Since: 2.24
  **/
 gconstpointer
@@ -1158,7 +1187,6 @@ g_variant_get_fixed_array (GVariant *value,
  * @elements: a pointer to the fixed array of contiguous elements
  * @n_elements: the number of elements
  * @element_size: the size of each element
- * @returns: (transfer none): a floating reference to a new array #GVariant instance
  *
  * Provides access to the serialised data for an array of fixed-sized
  * items.
@@ -1175,6 +1203,8 @@ g_variant_get_fixed_array (GVariant *value,
  * @n_elements, which must be non-%NULL is set equal to the number of
  * items in the array.
  *
+ * Returns: (transfer none): a floating reference to a new array #GVariant instance
+ *
  * Since: 2.32
  **/
 GVariant *
@@ -1221,12 +1251,13 @@ g_variant_new_fixed_array (const GVariantType  *element_type,
 /**
  * g_variant_new_string:
  * @string: a normal utf8 nul-terminated string
- * @returns: (transfer none): a floating reference to a new string #GVariant instance
  *
  * Creates a string #GVariant with the contents of @string.
  *
  * @string must be valid utf8.
  *
+ * Returns: (transfer none): a floating reference to a new string #GVariant instance
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -1242,12 +1273,13 @@ g_variant_new_string (const gchar *string)
 /**
  * g_variant_new_object_path:
  * @object_path: a normal C nul-terminated string
- * @returns: (transfer none): a floating reference to a new object path #GVariant instance
  *
  * Creates a D-Bus object path #GVariant with the contents of @string.
  * @string must be a valid D-Bus object path.  Use
  * g_variant_is_object_path() if you're not sure.
  *
+ * Returns: (transfer none): a floating reference to a new object path #GVariant instance
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -1262,7 +1294,6 @@ g_variant_new_object_path (const gchar *object_path)
 /**
  * g_variant_is_object_path:
  * @string: a normal C nul-terminated string
- * @returns: %TRUE if @string is a D-Bus object path
  *
  * Determines if a given string is a valid D-Bus object path.  You
  * should ensure that a string is a valid D-Bus object path before
@@ -1273,6 +1304,8 @@ g_variant_new_object_path (const gchar *object_path)
  * must contain only the characters "[A-Z][a-z][0-9]_".  No sequence
  * (including the one following the final '/' character) may be empty.
  *
+ * Returns: %TRUE if @string is a D-Bus object path
+ *
  * Since: 2.24
  **/
 gboolean
@@ -1286,12 +1319,13 @@ g_variant_is_object_path (const gchar *string)
 /**
  * g_variant_new_signature:
  * @signature: a normal C nul-terminated string
- * @returns: (transfer none): a floating reference to a new signature #GVariant instance
  *
  * Creates a D-Bus type signature #GVariant with the contents of
  * @string.  @string must be a valid D-Bus type signature.  Use
  * g_variant_is_signature() if you're not sure.
  *
+ * Returns: (transfer none): a floating reference to a new signature #GVariant instance
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -1306,7 +1340,6 @@ g_variant_new_signature (const gchar *signature)
 /**
  * g_variant_is_signature:
  * @string: a normal C nul-terminated string
- * @returns: %TRUE if @string is a D-Bus type signature
  *
  * Determines if a given string is a valid D-Bus type signature.  You
  * should ensure that a string is a valid D-Bus type signature before
@@ -1315,6 +1348,8 @@ g_variant_new_signature (const gchar *signature)
  * D-Bus type signatures consist of zero or more definite #GVariantType
  * strings in sequence.
  *
+ * Returns: %TRUE if @string is a D-Bus type signature
+ *
  * Since: 2.24
  **/
 gboolean
@@ -1330,7 +1365,6 @@ g_variant_is_signature (const gchar *string)
  * @value: a string #GVariant instance
  * @length: (allow-none) (default 0) (out): a pointer to a #gsize,
  *          to store the length
- * @returns: (transfer none): the constant string, utf8 encoded
  *
  * Returns the string value of a #GVariant instance with a string
  * type.  This includes the types %G_VARIANT_TYPE_STRING,
@@ -1347,6 +1381,8 @@ g_variant_is_signature (const gchar *string)
  *
  * The return value remains valid as long as @value exists.
  *
+ * Returns: (transfer none): the constant string, utf8 encoded
+ *
  * Since: 2.24
  **/
 const gchar *
@@ -1408,7 +1444,6 @@ g_variant_get_string (GVariant *value,
  * g_variant_dup_string:
  * @value: a string #GVariant instance
  * @length: (out): a pointer to a #gsize, to store the length
- * @returns: (transfer full): a newly allocated string, utf8 encoded
  *
  * Similar to g_variant_get_string() except that instead of returning
  * a constant string, the string is duplicated.
@@ -1417,6 +1452,8 @@ g_variant_get_string (GVariant *value,
  *
  * The return value must be freed using g_free().
  *
+ * Returns: (transfer full): a newly allocated string, utf8 encoded
+ *
  * Since: 2.24
  **/
 gchar *
@@ -1430,13 +1467,14 @@ g_variant_dup_string (GVariant *value,
  * g_variant_new_strv:
  * @strv: (array length=length) (element-type utf8): an array of strings
  * @length: the length of @strv, or -1
- * @returns: (transfer none): a new floating #GVariant instance
  *
  * Constructs an array of strings #GVariant from the given array of
  * strings.
  *
  * If @length is -1 then @strv is %NULL-terminated.
  *
+ * Returns: (transfer none): a new floating #GVariant instance
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -1463,8 +1501,6 @@ g_variant_new_strv (const gchar * const *strv,
  * g_variant_get_strv:
  * @value: an array of strings #GVariant
  * @length: (out) (allow-none): the length of the result, or %NULL
- * @returns: (array length=length zero-terminated=1) (transfer container): an array of constant
- * strings
  *
  * Gets the contents of an array of strings #GVariant.  This call
  * makes a shallow copy; the return result should be released with
@@ -1477,6 +1513,8 @@ g_variant_new_strv (const gchar * const *strv,
  * For an empty array, @length will be set to 0 and a pointer to a
  * %NULL pointer will be returned.
  *
+ * Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings
+ *
  * Since: 2.24
  **/
 const gchar **
@@ -1513,7 +1551,6 @@ g_variant_get_strv (GVariant *value,
  * g_variant_dup_strv:
  * @value: an array of strings #GVariant
  * @length: (out) (allow-none): the length of the result, or %NULL
- * @returns: (array length=length zero-terminated=1) (transfer full): an array of strings
  *
  * Gets the contents of an array of strings #GVariant.  This call
  * makes a deep copy; the return result should be released with
@@ -1526,6 +1563,8 @@ g_variant_get_strv (GVariant *value,
  * For an empty array, @length will be set to 0 and a pointer to a
  * %NULL pointer will be returned.
  *
+ * Returns: (array length=length zero-terminated=1) (transfer full): an array of strings
+ *
  * Since: 2.24
  **/
 gchar **
@@ -1561,7 +1600,6 @@ g_variant_dup_strv (GVariant *value,
  * g_variant_new_objv:
  * @strv: (array length=length) (element-type utf8): an array of strings
  * @length: the length of @strv, or -1
- * @returns: (transfer none): a new floating #GVariant instance
  *
  * Constructs an array of object paths #GVariant from the given array of
  * strings.
@@ -1571,6 +1609,8 @@ g_variant_dup_strv (GVariant *value,
  *
  * If @length is -1 then @strv is %NULL-terminated.
  *
+ * Returns: (transfer none): a new floating #GVariant instance
+ *
  * Since: 2.30
  **/
 GVariant *
@@ -1597,8 +1637,6 @@ g_variant_new_objv (const gchar * const *strv,
  * g_variant_get_objv:
  * @value: an array of object paths #GVariant
  * @length: (out) (allow-none): the length of the result, or %NULL
- * @returns: (array length=length zero-terminated=1) (transfer container): an array of constant
- * strings
  *
  * Gets the contents of an array of object paths #GVariant.  This call
  * makes a shallow copy; the return result should be released with
@@ -1611,6 +1649,8 @@ g_variant_new_objv (const gchar * const *strv,
  * For an empty array, @length will be set to 0 and a pointer to a
  * %NULL pointer will be returned.
  *
+ * Returns: (array length=length zero-terminated=1) (transfer container): an array of constant strings
+ *
  * Since: 2.30
  **/
 const gchar **
@@ -1647,7 +1687,6 @@ g_variant_get_objv (GVariant *value,
  * g_variant_dup_objv:
  * @value: an array of object paths #GVariant
  * @length: (out) (allow-none): the length of the result, or %NULL
- * @returns: (array length=length zero-terminated=1) (transfer full): an array of strings
  *
  * Gets the contents of an array of object paths #GVariant.  This call
  * makes a deep copy; the return result should be released with
@@ -1660,6 +1699,8 @@ g_variant_get_objv (GVariant *value,
  * For an empty array, @length will be set to 0 and a pointer to a
  * %NULL pointer will be returned.
  *
+ * Returns: (array length=length zero-terminated=1) (transfer full): an array of strings
+ *
  * Since: 2.30
  **/
 gchar **
@@ -1696,7 +1737,6 @@ g_variant_dup_objv (GVariant *value,
  * g_variant_new_bytestring:
  * @string: (array zero-terminated=1) (element-type guint8): a normal
  *          nul-terminated string in no particular encoding
- * @returns: (transfer none): 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
@@ -1705,6 +1745,8 @@ g_variant_dup_objv (GVariant *value,
  * The nul terminator character at the end of the string is stored in
  * the array.
  *
+ * Returns: (transfer none): a floating reference to a new bytestring #GVariant instance
+ *
  * Since: 2.26
  **/
 GVariant *
@@ -1719,8 +1761,6 @@ g_variant_new_bytestring (const gchar *string)
 /**
  * g_variant_get_bytestring:
  * @value: an array-of-bytes #GVariant instance
- * @returns: (transfer none) (array zero-terminated=1) (element-type guint8):
- *           the constant string
  *
  * Returns the string value of a #GVariant instance with an
  * array-of-bytes type.  The string has no particular encoding.
@@ -1738,6 +1778,9 @@ g_variant_new_bytestring (const gchar *string)
  *
  * The return value remains valid as long as @value exists.
  *
+ * Returns: (transfer none) (array zero-terminated=1) (element-type guint8):
+ *          the constant string
+ *
  * Since: 2.26
  **/
 const gchar *
@@ -1763,14 +1806,15 @@ g_variant_get_bytestring (GVariant *value)
  * @value: an array-of-bytes #GVariant instance
  * @length: (out) (allow-none) (default NULL): a pointer to a #gsize, to store
  *          the length (not including the nul terminator)
- * @returns: (transfer full) (array zero-terminated=1 length=length)
- *           (element-type guint8): a newly allocated string
  *
  * Similar to g_variant_get_bytestring() except that instead of
  * returning a constant string, the string is duplicated.
  *
  * The return value must be freed using g_free().
  *
+ * Returns: (transfer full) (array zero-terminated=1 length=length)
+ *          (element-type guint8): a newly allocated string
+ *
  * Since: 2.26
  **/
 gchar *
@@ -1796,13 +1840,14 @@ g_variant_dup_bytestring (GVariant *value,
  * g_variant_new_bytestring_array:
  * @strv: (array length=length): an array of strings
  * @length: the length of @strv, or -1
- * @returns: (transfer none): a new floating #GVariant instance
  *
  * Constructs an array of bytestring #GVariant from the given array of
  * strings.
  *
  * If @length is -1 then @strv is %NULL-terminated.
  *
+ * Returns: (transfer none): a new floating #GVariant instance
+ *
  * Since: 2.26
  **/
 GVariant *
@@ -1829,7 +1874,6 @@ g_variant_new_bytestring_array (const gchar * const *strv,
  * g_variant_get_bytestring_array:
  * @value: an array of array of bytes #GVariant ('aay')
  * @length: (out) (allow-none): the length of the result, or %NULL
- * @returns: (array length=length) (transfer container): an array of constant strings
  *
  * Gets the contents of an array of array of bytes #GVariant.  This call
  * makes a shallow copy; the return result should be released with
@@ -1842,6 +1886,8 @@ g_variant_new_bytestring_array (const gchar * const *strv,
  * For an empty array, @length will be set to 0 and a pointer to a
  * %NULL pointer will be returned.
  *
+ * Returns: (array length=length) (transfer container): an array of constant strings
+ *
  * Since: 2.26
  **/
 const gchar **
@@ -1878,7 +1924,6 @@ g_variant_get_bytestring_array (GVariant *value,
  * g_variant_dup_bytestring_array:
  * @value: an array of array of bytes #GVariant ('aay')
  * @length: (out) (allow-none): the length of the result, or %NULL
- * @returns: (array length=length) (transfer full): an array of strings
  *
  * Gets the contents of an array of array of bytes #GVariant.  This call
  * makes a deep copy; the return result should be released with
@@ -1891,6 +1936,8 @@ g_variant_get_bytestring_array (GVariant *value,
  * For an empty array, @length will be set to 0 and a pointer to a
  * %NULL pointer will be returned.
  *
+ * Returns: (array length=length) (transfer full): an array of strings
+ *
  * Since: 2.26
  **/
 gchar **
@@ -1927,13 +1974,14 @@ g_variant_dup_bytestring_array (GVariant *value,
 /**
  * g_variant_get_type:
  * @value: a #GVariant
- * @returns: a #GVariantType
  *
  * Determines the type of @value.
  *
  * The return value is valid for the lifetime of @value and must not
  * be freed.
  *
+ * Returns: a #GVariantType
+ *
  * Since: 2.24
  **/
 const GVariantType *
@@ -1951,12 +1999,13 @@ g_variant_get_type (GVariant *value)
 /**
  * g_variant_get_type_string:
  * @value: a #GVariant
- * @returns: the type string for the type of @value
  *
  * Returns the type string of @value.  Unlike the result of calling
  * g_variant_type_peek_string(), this string is nul-terminated.  This
  * string belongs to #GVariant and must not be freed.
  *
+ * Returns: the type string for the type of @value
+ *
  * Since: 2.24
  **/
 const gchar *
@@ -1975,10 +2024,11 @@ g_variant_get_type_string (GVariant *value)
  * g_variant_is_of_type:
  * @value: a #GVariant instance
  * @type: a #GVariantType
- * @returns: %TRUE if the type of @value matches @type
  *
  * Checks if a value has a type matching the provided type.
  *
+ * Returns: %TRUE if the type of @value matches @type
+ *
  * Since: 2.24
  **/
 gboolean
@@ -1991,9 +2041,12 @@ g_variant_is_of_type (GVariant           *value,
 /**
  * g_variant_is_container:
  * @value: a #GVariant instance
- * @returns: %TRUE if @value is a container
  *
  * Checks if @value is a container.
+ *
+ * Returns: %TRUE if @value is a container
+ *
+ * Since: 2.24
  */
 gboolean
 g_variant_is_container (GVariant *value)
@@ -2005,10 +2058,11 @@ g_variant_is_container (GVariant *value)
 /**
  * g_variant_classify:
  * @value: a #GVariant
- * @returns: the #GVariantClass of @value
  *
  * Classifies @value according to its top-level type.
  *
+ * Returns: the #GVariantClass of @value
+ *
  * Since: 2.24
  **/
 /**
@@ -2047,7 +2101,7 @@ g_variant_classify (GVariant *value)
 }
 
 /* Pretty printer {{{1 */
-/* This function is not introspectable because if @string is NULL, 
+/* This function is not introspectable because if @string is NULL,
    @returns is (transfer full), otherwise it is (transfer none), which
    is not supported by GObjectIntrospection */
 /**
@@ -2056,13 +2110,14 @@ g_variant_classify (GVariant *value)
  * @string: (allow-none) (default NULL): a #GString, or %NULL
  * @type_annotate: %TRUE if type information should be included in
  *                 the output
- * @returns: a #GString containing the string
  *
  * Behaves as g_variant_print(), but operates on a #GString.
  *
  * If @string is non-%NULL then it is appended to and returned.  Else,
  * a new empty #GString is allocated and it is returned.
  *
+ * Returns: a #GString containing the string
+ *
  * Since: 2.24
  **/
 GString *
@@ -2474,7 +2529,6 @@ g_variant_print_string (GVariant *value,
  * @value: a #GVariant
  * @type_annotate: %TRUE if type information should be included in
  *                 the output
- * @returns: (transfer full): a newly-allocated string holding the result.
  *
  * Pretty-prints @value in the format understood by g_variant_parse().
  *
@@ -2482,6 +2536,10 @@ g_variant_print_string (GVariant *value,
  *
  * If @type_annotate is %TRUE, then type information is included in
  * the output.
+ *
+ * Returns: (transfer full): a newly-allocated string holding the result.
+ *
+ * Since: 2.24
  */
 gchar *
 g_variant_print (GVariant *value,
@@ -2495,7 +2553,6 @@ g_variant_print (GVariant *value,
 /**
  * g_variant_hash:
  * @value: (type GVariant): a basic #GVariant value as a #gconstpointer
- * @returns: a hash value corresponding to @value
  *
  * Generates a hash value for a #GVariant instance.
  *
@@ -2507,6 +2564,8 @@ g_variant_print (GVariant *value,
  * The type of @value is #gconstpointer only to allow use of this
  * function with #GHashTable.  @value must be a #GVariant.
  *
+ * Returns: a hash value corresponding to @value
+ *
  * Since: 2.24
  **/
 guint
@@ -2582,13 +2641,14 @@ g_variant_hash (gconstpointer value_)
  * g_variant_equal:
  * @one: (type GVariant): a #GVariant instance
  * @two: (type GVariant): a #GVariant instance
- * @returns: %TRUE if @one and @two are equal
  *
  * Checks if @one and @two have the same type and value.
  *
  * The types of @one and @two are #gconstpointer only to allow use of
  * this function with #GHashTable.  They must each be a #GVariant.
  *
+ * Returns: %TRUE if @one and @two are equal
+ *
  * Since: 2.24
  **/
 gboolean
@@ -2647,9 +2707,6 @@ g_variant_equal (gconstpointer one,
  * g_variant_compare:
  * @one: (type GVariant): a basic-typed #GVariant instance
  * @two: (type GVariant): a #GVariant instance of the same type
- * @returns: negative value if a &lt; b;
- *           zero if a = b;
- *           positive value if a &gt; b.
  *
  * Compares @one and @two.
  *
@@ -2671,6 +2728,10 @@ g_variant_equal (gconstpointer one,
  * If you only require an equality comparison, g_variant_equal() is more
  * general.
  *
+ * Returns: negative value if a &lt; b;
+ *          zero if a = b;
+ *          positive value if a &gt; b.
+ *
  * Since: 2.26
  **/
 gint
@@ -2788,7 +2849,6 @@ struct heap_iter
 /**
  * g_variant_iter_new:
  * @value: a container #GVariant
- * @returns: (transfer full): a new heap-allocated #GVariantIter
  *
  * Creates a heap-allocated #GVariantIter for iterating over the items
  * in @value.
@@ -2799,6 +2859,8 @@ struct heap_iter
  * A reference is taken to @value and will be released only when
  * g_variant_iter_free() is called.
  *
+ * Returns: (transfer full): a new heap-allocated #GVariantIter
+ *
  * Since: 2.24
  **/
 GVariantIter *
@@ -2819,7 +2881,6 @@ g_variant_iter_new (GVariant *value)
  * g_variant_iter_init: (skip)
  * @iter: a pointer to a #GVariantIter
  * @value: a container #GVariant
- * @returns: the number of items in @value
  *
  * Initialises (without allocating) a #GVariantIter.  @iter may be
  * completely uninitialised prior to this call; its old value is
@@ -2828,6 +2889,8 @@ g_variant_iter_new (GVariant *value)
  * The iterator remains valid for as long as @value exists, and need not
  * be freed in any way.
  *
+ * Returns: the number of items in @value
+ *
  * Since: 2.24
  **/
 gsize
@@ -2846,7 +2909,6 @@ g_variant_iter_init (GVariantIter *iter,
 /**
  * g_variant_iter_copy:
  * @iter: a #GVariantIter
- * @returns: (transfer full): a new heap-allocated #GVariantIter
  *
  * Creates a new heap-allocated #GVariantIter to iterate over the
  * container that was being iterated over by @iter.  Iteration begins on
@@ -2859,6 +2921,8 @@ g_variant_iter_init (GVariantIter *iter,
  * A reference is taken to the container that @iter is iterating over
  * and will be releated only when g_variant_iter_free() is called.
  *
+ * Returns: (transfer full): a new heap-allocated #GVariantIter
+ *
  * Since: 2.24
  **/
 GVariantIter *
@@ -2877,7 +2941,6 @@ g_variant_iter_copy (GVariantIter *iter)
 /**
  * g_variant_iter_n_children:
  * @iter: a #GVariantIter
- * @returns: the number of children in the container
  *
  * Queries the number of child items in the container that we are
  * iterating over.  This is the total number of items -- not the number
@@ -2885,6 +2948,8 @@ g_variant_iter_copy (GVariantIter *iter)
  *
  * This function might be useful for preallocation of arrays.
  *
+ * Returns: the number of children in the container
+ *
  * Since: 2.24
  **/
 gsize
@@ -2919,7 +2984,6 @@ g_variant_iter_free (GVariantIter *iter)
 /**
  * g_variant_iter_next_value:
  * @iter: a #GVariantIter
- * @returns: (allow-none) (transfer full): a #GVariant, or %NULL
  *
  * Gets the next item in the container.  If no more items remain then
  * %NULL is returned.
@@ -2951,6 +3015,8 @@ g_variant_iter_free (GVariantIter *iter)
  * </programlisting>
  * </example>
  *
+ * Returns: (allow-none) (transfer full): a #GVariant, or %NULL
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -3524,7 +3590,6 @@ g_variant_builder_end (GVariantBuilder *builder)
  *         or %NULL
  * @endptr: (allow-none) (default NULL): location to store the end pointer,
  *          or %NULL
- * @returns: %TRUE if there was a valid format string
  *
  * Checks the string pointed to by @string for starting with a properly
  * formed #GVariant varargs format string.  If no valid format string is
@@ -3541,6 +3606,8 @@ g_variant_builder_end (GVariantBuilder *builder)
  * See the section on <link linkend='gvariant-format-strings'>GVariant
  * Format Strings</link>.
  *
+ * Returns: %TRUE if there was a valid format string
+ *
  * Since: 2.24
  */
 gboolean
@@ -3671,7 +3738,6 @@ g_variant_format_string_scan (const gchar  *string,
  *         or %NULL
  * @endptr: (allow-none) (default NULL): location to store the end pointer,
  *          or %NULL
- * @returns: (allow-none): a #GVariantType if there was a valid format string
  *
  * If @string starts with a valid format string then this function will
  * return the type that the format string corresponds to.  Otherwise
@@ -3683,6 +3749,8 @@ g_variant_format_string_scan (const gchar  *string,
  * This function is otherwise exactly like
  * g_variant_format_string_scan().
  *
+ * Returns: (allow-none): a #GVariantType if there was a valid format string
+ *
  * Since: 2.24
  */
 GVariantType *
@@ -4424,7 +4492,6 @@ g_variant_valist_get (const gchar **str,
  * g_variant_new: (skip)
  * @format_string: a #GVariant format string
  * @...: arguments, as per @format_string
- * @returns: a new floating #GVariant instance
  *
  * Creates a new #GVariant instance.
  *
@@ -4440,6 +4507,8 @@ g_variant_valist_get (const gchar **str,
  * 'r'; in essence, a new #GVariant must always be constructed by this
  * function (and not merely passed through it unmodified).
  *
+ * Returns: a new floating #GVariant instance
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -4467,7 +4536,6 @@ g_variant_new (const gchar *format_string,
  * @endptr: (allow-none) (default NULL): location to store the end pointer,
  *          or %NULL
  * @app: a pointer to a #va_list
- * @returns: a new, usually floating, #GVariant
  *
  * This function is intended to be used by libraries based on
  * #GVariant that want to provide g_variant_new()-like functionality
@@ -4502,6 +4570,8 @@ g_variant_new (const gchar *format_string,
  * result.  This can also be done by adding the result to a container,
  * or by passing it to another g_variant_new() call.
  *
+ * Returns: a new, usually floating, #GVariant
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -4701,8 +4771,6 @@ g_variant_get_child (GVariant    *value,
  * @iter: a #GVariantIter
  * @format_string: a GVariant format string
  * @...: the arguments to unpack the value into
- * @returns: %TRUE if a value was unpacked, or %FALSE if there as no
- *           value
  *
  * Gets the next item in the container and unpacks it into the variable
  * argument list according to @format_string, returning %TRUE.
@@ -4745,6 +4813,8 @@ g_variant_get_child (GVariant    *value,
  * For a solution that is likely to be more convenient to C programmers
  * when dealing with loops, see g_variant_iter_loop().
  *
+ * Returns: %TRUE if a value was unpacked, or %FALSE if there as no value
+ *
  * Since: 2.24
  **/
 gboolean
@@ -4778,8 +4848,6 @@ g_variant_iter_next (GVariantIter *iter,
  * @iter: a #GVariantIter
  * @format_string: a GVariant format string
  * @...: the arguments to unpack the value into
- * @returns: %TRUE if a value was unpacked, or %FALSE if there was no
- *           value
  *
  * Gets the next item in the container and unpacks it into the variable
  * argument list according to @format_string, returning %TRUE.
@@ -4838,6 +4906,9 @@ g_variant_iter_next (GVariantIter *iter,
  * types, use the '&' prefix to avoid allocating any memory at all (and
  * thereby avoiding the need to free anything as well).
  *
+ * Returns: %TRUE if a value was unpacked, or %FALSE if there was no
+ *          value
+ *
  * Since: 2.24
  **/
 gboolean
@@ -4952,7 +5023,6 @@ g_variant_deep_copy (GVariant *value)
 /**
  * g_variant_get_normal_form:
  * @value: a #GVariant
- * @returns: (transfer full): a trusted #GVariant
  *
  * Gets a #GVariant instance that has the same value as @value and is
  * trusted to be in normal form.
@@ -4971,6 +5041,8 @@ g_variant_deep_copy (GVariant *value)
  * data from untrusted sources and you want to ensure your serialised
  * output is definitely in normal form.
  *
+ * Returns: (transfer full): a trusted #GVariant
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -4990,7 +5062,6 @@ g_variant_get_normal_form (GVariant *value)
 /**
  * g_variant_byteswap:
  * @value: a #GVariant
- * @returns: (transfer full): the byteswapped form of @value
  *
  * Performs a byteswapping operation on the contents of @value.  The
  * result is that all multi-byte numeric data contained in @value is
@@ -5004,6 +5075,8 @@ g_variant_get_normal_form (GVariant *value)
  *
  * The returned value is always in normal form and is marked as trusted.
  *
+ * Returns: (transfer full): the byteswapped form of @value
+ *
  * Since: 2.24
  **/
 GVariant *
@@ -5052,7 +5125,6 @@ g_variant_byteswap (GVariant *value)
  * @trusted: %TRUE if @data is definitely in normal form
  * @notify: (scope async): function to call when @data is no longer needed
  * @user_data: data for @notify
- * @returns: (transfer none): a new floating #GVariant of type @type
  *
  * Creates a new #GVariant instance from serialised data.
  *
@@ -5079,6 +5151,8 @@ g_variant_byteswap (GVariant *value)
  * needed.  The exact time of this call is unspecified and might even be
  * before this function returns.
  *
+ * Returns: (transfer none): a new floating #GVariant of type @type
+ *
  * Since: 2.24
  **/
 GVariant *
diff --git a/glib/gvarianttype.c b/glib/gvarianttype.c
index 2bdbcaac0..a242a3845 100644
--- a/glib/gvarianttype.c
+++ b/glib/gvarianttype.c
@@ -504,7 +504,6 @@ g_variant_type_check (const GVariantType *type)
  * @string: a pointer to any string
  * @limit: (allow-none): the end of @string, or %NULL
  * @endptr: (out) (allow-none): location to store the end pointer, or %NULL
- * @returns: %TRUE if a valid type string was found
  *
  * Scan for a single complete and valid GVariant type string in @string.
  * The memory pointed to by @limit (or bytes beyond it) is never
@@ -520,6 +519,8 @@ g_variant_type_check (const GVariantType *type)
  * For the simple case of checking if a string is a valid type string,
  * see g_variant_type_string_is_valid().
  *
+ * Returns: %TRUE if a valid type string was found
+ *
  * Since: 2.24
  **/
 gboolean
@@ -572,12 +573,13 @@ g_variant_type_string_scan (const gchar  *string,
 /**
  * g_variant_type_string_is_valid:
  * @type_string: a pointer to any string
- * @returns: %TRUE if @type_string is exactly one valid type string
  *
  * Checks if @type_string is a valid GVariant type string.  This call is
  * equivalent to calling g_variant_type_string_scan() and confirming
  * that the following character is a nul terminator.
  *
+ * Returns: %TRUE if @type_string is exactly one valid type string
+ *
  * Since 2.24
  **/
 gboolean
@@ -616,11 +618,12 @@ g_variant_type_free (GVariantType *type)
 /**
  * g_variant_type_copy:
  * @type: a #GVariantType
- * @returns: (transfer full): a new #GVariantType
  *
  * Makes a copy of a #GVariantType.  It is appropriate to call
  * g_variant_type_free() on the return value.  @type may not be %NULL.
  *
+ * Returns: (transfer full): a new #GVariantType
+ *
  * Since 2.24
  **/
 GVariantType *
@@ -643,7 +646,6 @@ g_variant_type_copy (const GVariantType *type)
 /**
  * g_variant_type_new:
  * @type_string: a valid GVariant type string
- * @returns: (transfer full): a new #GVariantType
  *
  * Creates a new #GVariantType corresponding to the type string given
  * by @type_string.  It is appropriate to call g_variant_type_free() on
@@ -652,6 +654,8 @@ g_variant_type_copy (const GVariantType *type)
  * It is a programmer error to call this function with an invalid type
  * string.  Use g_variant_type_string_is_valid() if you are unsure.
  *
+ * Returns: (transfer full): a new #GVariantType
+ *
  * Since: 2.24
  */
 GVariantType *
@@ -665,12 +669,13 @@ g_variant_type_new (const gchar *type_string)
 /**
  * g_variant_type_get_string_length:
  * @type: a #GVariantType
- * @returns: the length of the corresponding type string
  *
  * Returns the length of the type string corresponding to the given
  * @type.  This function must be used to determine the valid extent of
  * the memory region returned by g_variant_type_peek_string().
  *
+ * Returns: the length of the corresponding type string
+ *
  * Since 2.24
  **/
 gsize
@@ -707,7 +712,6 @@ g_variant_type_get_string_length (const GVariantType *type)
 /**
  * g_variant_type_peek_string: (skip)
  * @type: a #GVariantType
- * @returns: the corresponding type string (not nul-terminated)
  *
  * Returns the type string corresponding to the given @type.  The
  * result is not nul-terminated; in order to determine its length you
@@ -715,6 +719,8 @@ g_variant_type_get_string_length (const GVariantType *type)
  *
  * To get a nul-terminated string, see g_variant_type_dup_string().
  *
+ * Returns: the corresponding type string (not nul-terminated)
+ *
  * Since 2.24
  **/
 const gchar *
@@ -728,12 +734,13 @@ g_variant_type_peek_string (const GVariantType *type)
 /**
  * g_variant_type_dup_string:
  * @type: a #GVariantType
- * @returns: (transfer full): the corresponding type string
  *
  * Returns a newly-allocated copy of the type string corresponding to
  * @type.  The returned string is nul-terminated.  It is appropriate to
  * call g_free() on the return value.
  *
+ * Returns: (transfer full): the corresponding type string
+ *
  * Since 2.24
  **/
 gchar *
@@ -748,7 +755,6 @@ g_variant_type_dup_string (const GVariantType *type)
 /**
  * g_variant_type_is_definite:
  * @type: a #GVariantType
- * @returns: %TRUE if @type is definite
  *
  * Determines if the given @type is definite (ie: not indefinite).
  *
@@ -761,6 +767,8 @@ g_variant_type_dup_string (const GVariantType *type)
  * indefinite type like %G_VARIANT_TYPE_ARRAY, however, will result in
  * %FALSE being returned.
  *
+ * Returns: %TRUE if @type is definite
+ *
  * Since 2.24
  **/
 gboolean
@@ -787,7 +795,6 @@ g_variant_type_is_definite (const GVariantType *type)
 /**
  * g_variant_type_is_container:
  * @type: a #GVariantType
- * @returns: %TRUE if @type is a container type
  *
  * Determines if the given @type is a container type.
  *
@@ -798,6 +805,8 @@ g_variant_type_is_definite (const GVariantType *type)
  * definite subtype is a container -- %G_VARIANT_TYPE_ARRAY, for
  * example.
  *
+ * Returns: %TRUE if @type is a container type
+ *
  * Since 2.24
  **/
 gboolean
@@ -826,7 +835,6 @@ g_variant_type_is_container (const GVariantType *type)
 /**
  * g_variant_type_is_basic:
  * @type: a #GVariantType
- * @returns: %TRUE if @type is a basic type
  *
  * Determines if the given @type is a basic type.
  *
@@ -838,6 +846,8 @@ g_variant_type_is_container (const GVariantType *type)
  * This function returns %FALSE for all indefinite types except
  * %G_VARIANT_TYPE_BASIC.
  *
+ * Returns: %TRUE if @type is a basic type
+ *
  * Since 2.24
  **/
 gboolean
@@ -874,7 +884,6 @@ g_variant_type_is_basic (const GVariantType *type)
 /**
  * g_variant_type_is_maybe:
  * @type: a #GVariantType
- * @returns: %TRUE if @type is a maybe type
  *
  * Determines if the given @type is a maybe type.  This is true if the
  * type string for @type starts with an 'm'.
@@ -883,6 +892,8 @@ g_variant_type_is_basic (const GVariantType *type)
  * definite subtype is a maybe type -- %G_VARIANT_TYPE_MAYBE, for
  * example.
  *
+ * Returns: %TRUE if @type is a maybe type
+ *
  * Since 2.24
  **/
 gboolean
@@ -896,7 +907,6 @@ g_variant_type_is_maybe (const GVariantType *type)
 /**
  * g_variant_type_is_array:
  * @type: a #GVariantType
- * @returns: %TRUE if @type is an array type
  *
  * Determines if the given @type is an array type.  This is true if the
  * type string for @type starts with an 'a'.
@@ -905,6 +915,8 @@ g_variant_type_is_maybe (const GVariantType *type)
  * definite subtype is an array type -- %G_VARIANT_TYPE_ARRAY, for
  * example.
  *
+ * Returns: %TRUE if @type is an array type
+ *
  * Since 2.24
  **/
 gboolean
@@ -918,7 +930,6 @@ g_variant_type_is_array (const GVariantType *type)
 /**
  * g_variant_type_is_tuple:
  * @type: a #GVariantType
- * @returns: %TRUE if @type is a tuple type
  *
  * Determines if the given @type is a tuple type.  This is true if the
  * type string for @type starts with a '(' or if @type is
@@ -928,6 +939,8 @@ g_variant_type_is_array (const GVariantType *type)
  * definite subtype is a tuple type -- %G_VARIANT_TYPE_TUPLE, for
  * example.
  *
+ * Returns: %TRUE if @type is a tuple type
+ *
  * Since 2.24
  **/
 gboolean
@@ -944,7 +957,6 @@ g_variant_type_is_tuple (const GVariantType *type)
 /**
  * g_variant_type_is_dict_entry:
  * @type: a #GVariantType
- * @returns: %TRUE if @type is a dictionary entry type
  *
  * Determines if the given @type is a dictionary entry type.  This is
  * true if the type string for @type starts with a '{'.
@@ -953,6 +965,8 @@ g_variant_type_is_tuple (const GVariantType *type)
  * definite subtype is a dictionary entry type --
  * %G_VARIANT_TYPE_DICT_ENTRY, for example.
  *
+ * Returns: %TRUE if @type is a dictionary entry type
+ *
  * Since 2.24
  **/
 gboolean
@@ -966,10 +980,11 @@ g_variant_type_is_dict_entry (const GVariantType *type)
 /**
  * g_variant_type_is_variant:
  * @type: a #GVariantType
- * @returns: %TRUE if @type is the variant type
  *
  * Determines if the given @type is the variant type.
  *
+ * Returns: %TRUE if @type is the variant type
+ *
  * Since 2.24
  **/
 gboolean
@@ -983,7 +998,6 @@ g_variant_type_is_variant (const GVariantType *type)
 /**
  * g_variant_type_hash:
  * @type: (type GVariantType): a #GVariantType
- * @returns: the hash value
  *
  * Hashes @type.
  *
@@ -991,6 +1005,8 @@ g_variant_type_is_variant (const GVariantType *type)
  * #GHashTable without function pointer casting.  A valid
  * #GVariantType must be provided.
  *
+ * Returns: the hash value
+ *
  * Since 2.24
  **/
 guint
@@ -1016,7 +1032,6 @@ g_variant_type_hash (gconstpointer type)
  * g_variant_type_equal:
  * @type1: (type GVariantType): a #GVariantType
  * @type2: (type GVariantType): a #GVariantType
- * @returns: %TRUE if @type1 and @type2 are exactly equal
  *
  * Compares @type1 and @type2 for equality.
  *
@@ -1029,6 +1044,8 @@ g_variant_type_hash (gconstpointer type)
  * allow use with #GHashTable without function pointer casting.  For
  * both arguments, a valid #GVariantType must be provided.
  *
+ * Returns: %TRUE if @type1 and @type2 are exactly equal
+ *
  * Since 2.24
  **/
 gboolean
@@ -1060,7 +1077,6 @@ g_variant_type_equal (gconstpointer type1,
  * g_variant_type_is_subtype_of:
  * @type: a #GVariantType
  * @supertype: a #GVariantType
- * @returns: %TRUE if @type is a subtype of @supertype
  *
  * Checks if @type is a subtype of @supertype.
  *
@@ -1068,6 +1084,8 @@ g_variant_type_equal (gconstpointer type1,
  * types are considered to be subtypes of themselves.  Aside from that,
  * only indefinite types can have subtypes.
  *
+ * Returns: %TRUE if @type is a subtype of @supertype
+ *
  * Since 2.24
  **/
 gboolean
@@ -1133,12 +1151,13 @@ g_variant_type_is_subtype_of (const GVariantType *type,
 /**
  * g_variant_type_element:
  * @type: an array or maybe #GVariantType
- * @returns: (transfer none): the element type of @type
  *
  * Determines the element type of an array or maybe type.
  *
  * This function may only be used with array or maybe types.
  *
+ * Returns: (transfer none): the element type of @type
+ *
  * Since 2.24
  **/
 const GVariantType *
@@ -1158,7 +1177,6 @@ g_variant_type_element (const GVariantType *type)
 /**
  * g_variant_type_first:
  * @type: a tuple or dictionary entry #GVariantType
- * @returns: (transfer none): the first item type of @type, or %NULL
  *
  * Determines the first item type of a tuple or dictionary entry
  * type.
@@ -1175,6 +1193,8 @@ g_variant_type_element (const GVariantType *type)
  * This call, together with g_variant_type_next() provides an iterator
  * interface over tuple and dictionary entry types.
  *
+ * Returns: (transfer none): the first item type of @type, or %NULL
+ *
  * Since 2.24
  **/
 const GVariantType *
@@ -1196,7 +1216,6 @@ g_variant_type_first (const GVariantType *type)
 /**
  * g_variant_type_next:
  * @type: a #GVariantType from a previous call
- * @returns: (transfer none): the next #GVariantType after @type, or %NULL
  *
  * Determines the next item type of a tuple or dictionary entry
  * type.
@@ -1210,6 +1229,8 @@ g_variant_type_first (const GVariantType *type)
  *
  * For tuples, %NULL is returned when @type is the last item in a tuple.
  *
+ * Returns: (transfer none): the next #GVariantType after @type, or %NULL
+ *
  * Since 2.24
  **/
 const GVariantType *
@@ -1231,7 +1252,6 @@ g_variant_type_next (const GVariantType *type)
 /**
  * g_variant_type_n_items:
  * @type: a tuple or dictionary entry #GVariantType
- * @returns: the number of items in @type
  *
  * Determines the number of items contained in a tuple or
  * dictionary entry type.
@@ -1243,6 +1263,8 @@ g_variant_type_next (const GVariantType *type)
  * In the case of a dictionary entry type, this function will always
  * return 2.
  *
+ * Returns: the number of items in @type
+ *
  * Since 2.24
  **/
 gsize
@@ -1263,7 +1285,6 @@ g_variant_type_n_items (const GVariantType *type)
 /**
  * g_variant_type_key:
  * @type: a dictionary entry #GVariantType
- * @returns: (transfer none): the key type of the dictionary entry
  *
  * Determines the key type of a dictionary entry type.
  *
@@ -1271,6 +1292,8 @@ g_variant_type_n_items (const GVariantType *type)
  * than the additional restriction, this call is equivalent to
  * g_variant_type_first().
  *
+ * Returns: (transfer none): the key type of the dictionary entry
+ *
  * Since 2.24
  **/
 const GVariantType *
@@ -1289,12 +1312,13 @@ g_variant_type_key (const GVariantType *type)
 /**
  * g_variant_type_value:
  * @type: a dictionary entry #GVariantType
- * @returns: (transfer none): the value type of the dictionary entry
  *
  * Determines the value type of a dictionary entry type.
  *
  * This function may only be used with a dictionary entry type.
  *
+ * Returns: (transfer none): the value type of the dictionary entry
+ *
  * Since 2.24
  **/
 const GVariantType *
@@ -1314,7 +1338,6 @@ g_variant_type_value (const GVariantType *type)
  * g_variant_type_new_tuple:
  * @items: (array length=length): an array of #GVariantTypes, one for each item
  * @length: the length of @items, or -1
- * @returns: (transfer full): a new tuple #GVariantType
  *
  * Constructs a new tuple type, from @items.
  *
@@ -1323,6 +1346,8 @@ g_variant_type_value (const GVariantType *type)
  *
  * It is appropriate to call g_variant_type_free() on the return value.
  *
+ * Returns: (transfer full): a new tuple #GVariantType
+ *
  * Since 2.24
  **/
 static GVariantType *
@@ -1395,13 +1420,14 @@ g_variant_type_new_tuple (const GVariantType * const *items,
 /**
  * g_variant_type_new_array:
  * @element: a #GVariantType
- * @returns: (transfer full): a new array #GVariantType
  *
  * Constructs the type corresponding to an array of elements of the
  * type @type.
  *
  * It is appropriate to call g_variant_type_free() on the return value.
  *
+ * Returns: (transfer full): a new array #GVariantType
+ *
  * Since 2.24
  **/
 GVariantType *
@@ -1424,13 +1450,14 @@ g_variant_type_new_array (const GVariantType *element)
 /**
  * g_variant_type_new_maybe:
  * @element: a #GVariantType
- * @returns: (transfer full): a new maybe #GVariantType
  *
  * Constructs the type corresponding to a maybe instance containing
  * type @type or Nothing.
  *
  * It is appropriate to call g_variant_type_free() on the return value.
  *
+ * Returns: (transfer full): a new maybe #GVariantType
+ *
  * Since 2.24
  **/
 GVariantType *
@@ -1454,13 +1481,14 @@ g_variant_type_new_maybe (const GVariantType *element)
  * g_variant_type_new_dict_entry:
  * @key: a basic #GVariantType
  * @value: a #GVariantType
- * @returns: (transfer full): a new dictionary entry #GVariantType
  *
  * Constructs the type corresponding to a dictionary entry with a key
  * of type @key and a value of type @value.
  *
  * It is appropriate to call g_variant_type_free() on the return value.
  *
+ * Returns: (transfer full): a new dictionary entry #GVariantType
+ *
  * Since 2.24
  **/
 GVariantType *