[glib] Use "Returns:" instead of the invalid "@returns" for annotating return values.

[Robert Ancell <rancell src gnome org>]

commit 59a24ab5a3ffff7d2cd36a1b392b49cc4024c29d
Author: Robert Ancell <robert ancell canonical com>
Date:   Wed Oct 31 14:56:00 2012 +1300

    Use "Returns:" instead of the invalid "@returns" for annotating return values.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=673229

 gio/gvdb/gvdb-reader.c               |   27 ++++++---
 glib/deprecated/gcache.c             |    6 +-
 glib/deprecated/gcompletion.c        |   20 ++++---
 glib/deprecated/grel.c               |   18 ++++--
 glib/deprecated/gthread-deprecated.c |   23 +++++---
 glib/garray.c                        |  101 ++++++++++++++++++++++------------
 glib/gdataset.c                      |   19 ++++--
 glib/giochannel.c                    |    5 +-
 glib/giounix.c                       |    6 +-
 glib/giowin32.c                      |    9 ++-
 glib/glist.c                         |   21 ++++---
 glib/gnode.c                         |    3 +-
 glib/gpattern.c                      |   15 +++--
 glib/grand.c                         |    6 +-
 glib/gsequence.c                     |    7 +-
 glib/gslist.c                        |    6 +-
 glib/gthread.c                       |    3 +-
 glib/gtimer.c                        |    8 ++-
 glib/gtree.c                         |    3 +-
 glib/gvariant-parser.c               |    3 +-
 20 files changed, 200 insertions(+), 109 deletions(-)
---
diff --git a/gio/gvdb/gvdb-reader.c b/gio/gvdb/gvdb-reader.c
index 5c33434..44594bf 100644
--- a/gio/gvdb/gvdb-reader.c
+++ b/gio/gvdb/gvdb-reader.c
@@ -187,7 +187,6 @@ new_from_data (const void    *data,
  * @filename: the path to the hash file
  * @trusted: if the contents of @filename are trusted
  * @error: %NULL, or a pointer to a %NULL #GError
- * @returns: a new #GvdbTable
  *
  * Creates a new #GvdbTable from the contents of the file found at
  * @filename.
@@ -201,6 +200,8 @@ new_from_data (const void    *data,
  *
  * You should call gvdb_table_unref() on the return result when you no
  * longer require it.
+ *
+ * Returns: a new #GvdbTable
  **/
 GvdbTable *
 gvdb_table_new (const gchar  *filename,
@@ -230,7 +231,6 @@ gvdb_table_new (const gchar  *filename,
  * @user_data: User supplied data that owns @data
  * @ref: Ref function for @user_data
  * @unref: Unref function for @user_data
- * @returns: a new #GvdbTable
  *
  * Creates a new #GvdbTable from the data in @data.
  *
@@ -239,6 +239,8 @@ gvdb_table_new (const gchar  *filename,
  *
  * You should call gvdb_table_unref() on the return result when you no
  * longer require it.
+ *
+ * Returns: a new #GvdbTable
  **/
 GvdbTable *
 gvdb_table_new_from_data (const void    *data,
@@ -381,7 +383,6 @@ gvdb_table_list_from_item (GvdbTable                    *table,
  * gvdb_table_list:
  * @file: a #GvdbTable
  * @key: a string
- * @returns: a %NULL-terminated string array
  *
  * List all of the keys that appear below @key.  The nesting of keys
  * within the hash file is defined by the program that created the hash
@@ -394,6 +395,8 @@ gvdb_table_list_from_item (GvdbTable                    *table,
  *
  * You should call g_strfreev() on the return result when you no longer
  * require it.
+ *
+ * Returns: a %NULL-terminated string array
  **/
 gchar **
 gvdb_table_list (GvdbTable   *file,
@@ -444,12 +447,13 @@ gvdb_table_list (GvdbTable   *file,
  * gvdb_table_has_value:
  * @file: a #GvdbTable
  * @key: a string
- * @returns: %TRUE if @key is in the table
  *
  * Checks for a value named @key in @file.
  *
  * Note: this function does not consider non-value nodes (other hash
  * tables, for example).
+ *
+ * Returns: %TRUE if @key is in the table
  **/
 gboolean
 gvdb_table_has_value (GvdbTable    *file,
@@ -485,7 +489,6 @@ gvdb_table_value_from_item (GvdbTable                   *table,
  * gvdb_table_get_value:
  * @file: a #GvdbTable
  * @key: a string
- * @returns: a #GVariant, or %NULL
  *
  * Looks up a value named @key in @file.
  *
@@ -495,6 +498,8 @@ gvdb_table_value_from_item (GvdbTable                   *table,
  *
  * You should call g_variant_unref() on the return result when you no
  * longer require it.
+ *
+ * Returns: a #GVariant, or %NULL
  **/
 GVariant *
 gvdb_table_get_value (GvdbTable    *file,
@@ -524,12 +529,13 @@ gvdb_table_get_value (GvdbTable    *file,
  * gvdb_table_get_raw_value:
  * @table: a #GvdbTable
  * @key: a string
- * @returns: a #GVariant, or %NULL
  *
  * Looks up a value named @key in @file.
  *
  * This call is equivalent to gvdb_table_get_value() except that it
  * never byteswaps the value.
+ *
+ * Returns: a #GVariant, or %NULL
  **/
 GVariant *
 gvdb_table_get_raw_value (GvdbTable   *table,
@@ -547,7 +553,6 @@ gvdb_table_get_raw_value (GvdbTable   *table,
  * gvdb_table_get_table:
  * @file: a #GvdbTable
  * @key: a string
- * @returns: a new #GvdbTable, or %NULL
  *
  * Looks up the hash table named @key in @file.
  *
@@ -561,6 +566,8 @@ gvdb_table_get_raw_value (GvdbTable   *table,
  *
  * You should call gvdb_table_unref() on the return result when you no
  * longer require it.
+ *
+ * Returns: a new #GvdbTable, or %NULL
  **/
 GvdbTable *
 gvdb_table_get_table (GvdbTable   *file,
@@ -592,9 +599,10 @@ gvdb_table_get_table (GvdbTable   *file,
 /**
  * gvdb_table_ref:
  * @file: a #GvdbTable
- * @returns: a new reference on @file
  *
  * Increases the reference count on @file.
+ *
+ * Returns: a new reference on @file
  **/
 GvdbTable *
 gvdb_table_ref (GvdbTable *file)
@@ -626,13 +634,14 @@ gvdb_table_unref (GvdbTable *file)
 /**
  * gvdb_table_is_valid:
  * @table: a #GvdbTable
- * @returns: %TRUE if @table is still valid
  *
  * Checks if the table is still valid.
  *
  * An on-disk GVDB can be marked as invalid.  This happens when the file
  * has been replaced.  The appropriate action is typically to reopen the
  * file.
+ *
+ * Returns: %TRUE if @table is still valid
  **/
 gboolean
 gvdb_table_is_valid (GvdbTable *table)
diff --git a/glib/deprecated/gcache.c b/glib/deprecated/gcache.c
index 4968c32..5a59365 100644
--- a/glib/deprecated/gcache.c
+++ b/glib/deprecated/gcache.c
@@ -136,11 +136,12 @@ g_cache_node_destroy (GCacheNode *node)
 /**
  * GCacheNewFunc:
  * @key: a #GCache key
- * @Returns: a new #GCache value corresponding to the key.
  *
  * Specifies the type of the @value_new_func function passed to
  * g_cache_new(). It is passed a #GCache key and should create the
  * value corresponding to the key.
+ *
+ * Returns: a new #GCache value corresponding to the key.
  */
 
 /**
@@ -157,12 +158,13 @@ g_cache_node_destroy (GCacheNode *node)
  * GCacheDupFunc:
  * @value: the #GCache key to destroy (<emphasis>not</emphasis> a
  *         #GCache value as it seems)
- * @Returns: a copy of the #GCache key
  *
  * Specifies the type of the @key_dup_func function passed to
  * g_cache_new(). The function is passed a key
  * (<emphasis>not</emphasis> a value as the prototype implies) and
  * should return a duplicate of the key.
+ *
+ * Returns: a copy of the #GCache key
  */
 GCache*
 g_cache_new (GCacheNewFunc      value_new_func,
diff --git a/glib/deprecated/gcompletion.c b/glib/deprecated/gcompletion.c
index 7f7d7be..fb5ab61 100644
--- a/glib/deprecated/gcompletion.c
+++ b/glib/deprecated/gcompletion.c
@@ -86,11 +86,12 @@
 /**
  * GCompletionFunc:
  * @Param1: the completion item.
- * @Returns: the string corresponding to the item.
  *
  * Specifies the type of the function passed to g_completion_new(). It
  * should return the string corresponding to the given target item.
  * This is used when you use data structures as #GCompletion items.
+ *
+ * Returns: the string corresponding to the item.
  **/
 
 /**
@@ -98,14 +99,15 @@
  * @s1: string to compare with @s2.
  * @s2: string to compare with @s1.
  * @n: maximal number of bytes to compare.
- * @Returns: an integer less than, equal to, or greater than zero if
- *           the first @n bytes of @s1 is found, respectively, to be
- *           less than, to match, or to be greater than the first @n
- *           bytes of @s2.
  *
  * Specifies the type of the function passed to
  * g_completion_set_compare(). This is used when you use strings as
  * #GCompletion items.
+ *
+ * Returns: an integer less than, equal to, or greater than zero if
+ *          the first @n bytes of @s1 is found, respectively, to be
+ *          less than, to match, or to be greater than the first @n
+ *          bytes of @s2.
  **/
 
 static void completion_check_cache (GCompletion* cmp,
@@ -116,9 +118,10 @@ static void completion_check_cache (GCompletion* cmp,
  * @func: the function to be called to return the string representing
  *        an item in the #GCompletion, or %NULL if strings are going to
  *        be used as the #GCompletion items.
- * @Returns: the new #GCompletion.
  *
  * Creates a new #GCompletion.
+ *
+ * Returns: the new #GCompletion.
  **/
 GCompletion* 
 g_completion_new (GCompletionFunc func)
@@ -336,12 +339,13 @@ g_completion_complete_utf8 (GCompletion  *cmp,
  *              common to all items that matched @prefix, or %NULL if
  *              no items matched @prefix.  This string should be freed
  *              when no longer needed.
- * @Returns: (transfer none): the list of items whose strings begin with
- *           @prefix. This should not be changed.
  *
  * Attempts to complete the string @prefix using the #GCompletion
  * target items.
  *
+ * Returns: (transfer none): the list of items whose strings begin with
+ *          @prefix. This should not be changed.
+ *
  * Deprecated: 2.26: Rarely used API
  **/
 GList* 
diff --git a/glib/deprecated/grel.c b/glib/deprecated/grel.c
index a8b2c4d..7f6fdff 100644
--- a/glib/deprecated/grel.c
+++ b/glib/deprecated/grel.c
@@ -185,11 +185,12 @@ tuple_equal (gint fields)
 /**
  * g_relation_new:
  * @fields: the number of fields.
- * @Returns: a new #GRelation.
  *
  * Creates a new #GRelation with the given number of fields. Note that
  * currently the number of fields must be 2.
  *
+ * Returns: a new #GRelation.
+ *
  * Deprecated: 2.26: Rarely used API
  **/
 GRelation*
@@ -375,11 +376,12 @@ g_relation_delete_tuple (gpointer tuple_key,
  * @relation: a #GRelation.
  * @key: the value to compare with.
  * @field: the field of each record to match.
- * @Returns: the number of records deleted.
  *
  * Deletes any records from a #GRelation that have the given key value
  * in the given field.
  *
+ * Returns: the number of records deleted.
+ *
  * Deprecated: 2.26: Rarely used API
  **/
 gint
@@ -439,12 +441,13 @@ g_relation_select_tuple (gpointer tuple_key,
  * @relation: a #GRelation.
  * @key: the value to compare with.
  * @field: the field of each record to match.
- * @Returns: the records (tuples) that matched.
  *
  * Returns all of the tuples which have the given key in the given
  * field. Use g_tuples_index() to access the returned records. The
  * returned records should be freed with g_tuples_destroy().
  *
+ * Returns: the records (tuples) that matched.
+ *
  * Deprecated: 2.26: Rarely used API
  **/
 GTuples*
@@ -486,11 +489,12 @@ g_relation_select (GRelation     *relation,
  * @relation: a #GRelation.
  * @key: the value to compare with.
  * @field: the field of each record to match.
- * @Returns: the number of matches.
  *
  * Returns the number of tuples in a #GRelation that have the given
  * value in the given field.
  *
+ * Returns: the number of matches.
+ *
  * Deprecated: 2.26: Rarely used API
  **/
 gint
@@ -520,12 +524,13 @@ g_relation_count (GRelation     *relation,
  * @relation: a #GRelation.
  * @...: the fields of the record to compare. The number must match
  *       the number of fields in the #GRelation.
- * @Returns: %TRUE if a record matches.
  *
  * Returns %TRUE if a record with the given values exists in a
  * #GRelation. Note that the values are compared directly, so that, for
  * example, two copies of the same string will not match.
  *
+ * Returns: %TRUE if a record matches.
+ *
  * Deprecated: 2.26: Rarely used API
  **/
 gboolean
@@ -578,12 +583,13 @@ g_tuples_destroy (GTuples *tuples0)
  * @tuples: the tuple data, returned by g_relation_select().
  * @index_: the index of the record.
  * @field: the field to return.
- * @Returns: the field of the record.
  *
  * Gets a field from the records returned by g_relation_select(). It
  * returns the given field of the record at the given index. The
  * returned value should not be changed.
  *
+ * Returns: the field of the record.
+ *
  * Deprecated: 2.26: Rarely used API
  **/
 gpointer
diff --git a/glib/deprecated/gthread-deprecated.c b/glib/deprecated/gthread-deprecated.c
index 5e25ce8..a98fc95 100644
--- a/glib/deprecated/gthread-deprecated.c
+++ b/glib/deprecated/gthread-deprecated.c
@@ -351,10 +351,11 @@ g_thread_create (GThreadFunc   func,
  * @bound: ignored
  * @priority: ignored
  * @error: return location for error.
- * @Returns: the new #GThread on success.
  *
  * This function creates a new thread.
  *
+ * Returns: the new #GThread on success.
+ *
  * Deprecated:2.32: The @bound and @priority arguments are now ignored.
  * Use g_thread_new().
  */
@@ -501,12 +502,13 @@ g_static_mutex_init (GStaticMutex *mutex)
 /**
  * g_static_mutex_get_mutex:
  * @mutex: a #GStaticMutex.
- * @Returns: the #GMutex corresponding to @mutex.
  *
  * For some operations (like g_cond_wait()) you must have a #GMutex
  * instead of a #GStaticMutex. This function will return the
  * corresponding #GMutex for @mutex.
  *
+ * Returns: the #GMutex corresponding to @mutex.
+ *
  * Deprecated: 2.32: Just use a #GMutex
  */
 GMutex *
@@ -556,10 +558,11 @@ g_static_mutex_get_mutex_impl (GStaticMutex* mutex)
 /**
  * g_static_mutex_trylock:
  * @mutex: a #GStaticMutex.
- * @Returns: %TRUE, if the #GStaticMutex could be locked.
  *
  * Works like g_mutex_trylock(), but for a #GStaticMutex.
  *
+ * Returns: %TRUE, if the #GStaticMutex could be locked.
+ *
  * Deprecated: 2.32: Use g_mutex_trylock()
  */
 
@@ -716,7 +719,6 @@ g_static_rec_mutex_lock (GStaticRecMutex* mutex)
 /**
  * g_static_rec_mutex_trylock:
  * @mutex: a #GStaticRecMutex to lock.
- * @Returns: %TRUE, if @mutex could be locked.
  *
  * Tries to lock @mutex. If @mutex is already locked by another thread,
  * it immediately returns %FALSE. Otherwise it locks @mutex and returns
@@ -724,6 +726,8 @@ g_static_rec_mutex_lock (GStaticRecMutex* mutex)
  * functions increases the depth of @mutex and immediately returns
  * %TRUE.
  *
+ * Returns: %TRUE, if @mutex could be locked.
+ *
  * Deprecated: 2.32: Use g_rec_mutex_trylock()
  */
 gboolean
@@ -789,8 +793,6 @@ g_static_rec_mutex_lock_full (GStaticRecMutex *mutex,
 /**
  * g_static_rec_mutex_unlock_full:
  * @mutex: a #GStaticRecMutex to completely unlock.
- * @Returns: number of times @mutex has been locked by the current
- *           thread.
  *
  * Completely unlocks @mutex. If another thread is blocked in a
  * g_static_rec_mutex_lock() call for @mutex, it will be woken and can
@@ -800,6 +802,9 @@ g_static_rec_mutex_lock_full (GStaticRecMutex *mutex,
  * g_static_rec_mutex_lock_full() with the depth returned by this
  * function.
  *
+ * Returns: number of times @mutex has been locked by the current
+ *          thread.
+ *
  * Deprecated: 2.32: Use g_rec_mutex_unlock()
  */
 guint
@@ -1024,7 +1029,6 @@ g_static_rw_lock_reader_lock (GStaticRWLock* lock)
 /**
  * g_static_rw_lock_reader_trylock:
  * @lock: a #GStaticRWLock to lock for reading.
- * @Returns: %TRUE, if @lock could be locked for reading.
  *
  * Tries to lock @lock for reading. If @lock is already locked for
  * writing by another thread or if another thread is already waiting to
@@ -1032,6 +1036,8 @@ g_static_rw_lock_reader_lock (GStaticRWLock* lock)
  * @lock for reading and returns %TRUE. This lock has to be unlocked by
  * g_static_rw_lock_reader_unlock().
  *
+ * Returns: %TRUE, if @lock could be locked for reading.
+ *
  * Deprectated: 2.32: Use g_rw_lock_reader_trylock() instead
  */
 gboolean
@@ -1113,13 +1119,14 @@ g_static_rw_lock_writer_lock (GStaticRWLock* lock)
 /**
  * g_static_rw_lock_writer_trylock:
  * @lock: a #GStaticRWLock to lock for writing.
- * @Returns: %TRUE, if @lock could be locked for writing.
  *
  * Tries to lock @lock for writing. If @lock is already locked (for
  * either reading or writing) by another thread, it immediately returns
  * %FALSE. Otherwise it locks @lock for writing and returns %TRUE. This
  * lock has to be unlocked by g_static_rw_lock_writer_unlock().
  *
+ * Returns: %TRUE, if @lock could be locked for writing.
+ *
  * Deprectated: 2.32: Use g_rw_lock_writer_trylock() instead
  */
 gboolean
diff --git a/glib/garray.c b/glib/garray.c
index b88ae7b..bdcbc93 100644
--- a/glib/garray.c
+++ b/glib/garray.c
@@ -118,7 +118,6 @@ struct _GRealArray
  * @a: a #GArray.
  * @t: the type of the elements.
  * @i: the index of the element to return.
- * @Returns: the element of the #GArray at the index given by @i.
  *
  * Returns the element of a #GArray at the given index. The return
  * value is cast to the given type.
@@ -132,6 +131,8 @@ struct _GRealArray
  *   event = &amp;g_array_index (events, EDayViewEvent, 3);
  *  </programlisting>
  * </example>
+ *
+ * Returns: the element of the #GArray at the index given by @i.
  **/
 
 #define g_array_elt_len(array,i) ((array)->elt_size * (i))
@@ -154,9 +155,10 @@ static void  g_array_maybe_expand (GRealArray *array,
  * @clear_: %TRUE if #GArray elements should be automatically cleared
  *          to 0 when they are allocated.
  * @element_size: the size of each element in bytes.
- * @Returns: the new #GArray.
  *
  * Creates a new #GArray with a reference count of 1.
+ *
+ * Returns: the new #GArray.
  **/
 GArray*
 g_array_new (gboolean zero_terminated,
@@ -176,12 +178,13 @@ g_array_new (gboolean zero_terminated,
  *          allocation.
  * @element_size: size of each element in the array.
  * @reserved_size: number of elements preallocated.
- * @Returns: the new #GArray.
  *
  * Creates a new #GArray with @reserved_size elements preallocated and
  * a reference count of 1. This avoids frequent reallocation, if you
  * are going to add many elements to the array. Note however that the
  * size of the array is still 0.
+ *
+ * Returns: the new #GArray.
  **/
 GArray* g_array_sized_new (gboolean zero_terminated,
 			   gboolean clear,
@@ -315,8 +318,6 @@ g_array_get_element_size (GArray *array)
  * g_array_free:
  * @array: a #GArray.
  * @free_segment: if %TRUE the actual element data is freed as well.
- * @Returns: the element data if @free_segment is %FALSE, otherwise
- *           %NULL.  The element data should be freed using g_free().
  *
  * Frees the memory allocated for the #GArray. If @free_segment is
  * %TRUE it frees the memory block holding the elements as well and
@@ -328,6 +329,9 @@ g_array_get_element_size (GArray *array)
  *
  * <note><para>If array elements contain dynamically-allocated memory,
  * they should be freed separately.</para></note>
+ *
+ * Returns: the element data if @free_segment is %FALSE, otherwise
+ *          %NULL.  The element data should be freed using g_free().
  **/
 gchar*
 g_array_free (GArray   *farray,
@@ -388,15 +392,15 @@ array_free (GRealArray     *array,
  * @array: a #GArray.
  * @data: a pointer to the elements to append to the end of the array.
  * @len: the number of elements to append.
- * @Returns: the #GArray.
  *
  * Adds @len elements onto the end of the array.
+ *
+ * Returns: the #GArray.
  **/
 /**
  * g_array_append_val:
  * @a: a #GArray.
  * @v: the value to append to the #GArray.
- * @Returns: the #GArray.
  *
  * Adds the value on to the end of the array. The array will grow in
  * size automatically if necessary.
@@ -404,6 +408,8 @@ array_free (GRealArray     *array,
  * <note><para>g_array_append_val() is a macro which uses a reference
  * to the value parameter @v. This means that you cannot use it with
  * literal values such as "27". You must use variables.</para></note>
+ *
+ * Returns: the #GArray.
  **/
 GArray*
 g_array_append_vals (GArray       *farray,
@@ -432,19 +438,19 @@ g_array_append_vals (GArray       *farray,
  * @data: a pointer to the elements to prepend to the start of the
  *        array.
  * @len: the number of elements to prepend.
- * @Returns: the #GArray.
  *
  * Adds @len elements onto the start of the array.
  *
  * This operation is slower than g_array_append_vals() since the
  * existing elements in the array have to be moved to make space for
  * the new elements.
+ *
+ * Returns: the #GArray.
  **/
 /**
  * g_array_prepend_val:
  * @a: a #GArray.
  * @v: the value to prepend to the #GArray.
- * @Returns: the #GArray.
  *
  * Adds the value on to the start of the array. The array will grow in
  * size automatically if necessary.
@@ -456,6 +462,8 @@ g_array_append_vals (GArray       *farray,
  * <note><para>g_array_prepend_val() is a macro which uses a reference
  * to the value parameter @v. This means that you cannot use it with
  * literal values such as "27". You must use variables.</para></note>
+ *
+ * Returns: the #GArray.
  **/
 GArray*
 g_array_prepend_vals (GArray        *farray,
@@ -486,22 +494,24 @@ g_array_prepend_vals (GArray        *farray,
  * @index_: the index to place the elements at.
  * @data: a pointer to the elements to insert.
  * @len: the number of elements to insert.
- * @Returns: the #GArray.
  *
  * Inserts @len elements into a #GArray at the given index.
+ *
+ * Returns: the #GArray.
  **/
 /**
  * g_array_insert_val:
  * @a: a #GArray.
  * @i: the index to place the element at.
  * @v: the value to insert into the array.
- * @Returns: the #GArray.
  *
  * Inserts an element into an array at the given index.
  *
  * <note><para>g_array_insert_val() is a macro which uses a reference
  * to the value parameter @v. This means that you cannot use it with
  * literal values such as "27". You must use variables.</para></note>
+ *
+ * Returns: the #GArray.
  **/
 GArray*
 g_array_insert_vals (GArray        *farray,
@@ -532,10 +542,11 @@ g_array_insert_vals (GArray        *farray,
  * g_array_set_size:
  * @array: a #GArray.
  * @length: the new size of the #GArray.
- * @Returns: the #GArray.
  *
  * Sets the size of the array, expanding it if necessary. If the array
  * was created with @clear_ set to %TRUE, the new elements are set to 0.
+ *
+ * Returns: the #GArray.
  **/
 GArray*
 g_array_set_size (GArray *farray,
@@ -566,10 +577,11 @@ g_array_set_size (GArray *farray,
  * g_array_remove_index:
  * @array: a #GArray.
  * @index_: the index of the element to remove.
- * @Returns: the #GArray.
  *
  * Removes the element at the given index from a #GArray. The following
  * elements are moved down one place.
+ *
+ * Returns: the #GArray.
  **/
 GArray*
 g_array_remove_index (GArray *farray,
@@ -603,12 +615,13 @@ g_array_remove_index (GArray *farray,
  * g_array_remove_index_fast:
  * @array: a @GArray.
  * @index_: the index of the element to remove.
- * @Returns: the #GArray.
  *
  * Removes the element at the given index from a #GArray. The last
  * element in the array is used to fill in the space, so this function
  * does not preserve the order of the #GArray. But it is faster than
  * g_array_remove_index().
+ *
+ * Returns: the #GArray.
  **/
 GArray*
 g_array_remove_index_fast (GArray *farray,
@@ -643,11 +656,12 @@ g_array_remove_index_fast (GArray *farray,
  * @array: a @GArray.
  * @index_: the index of the first element to remove.
  * @length: the number of elements to remove.
- * @Returns: the #GArray.
  *
  * Removes the given number of elements starting at the given index
  * from a #GArray.  The following elements are moved to close the gap.
  *
+ * Returns: the #GArray.
+ *
  * Since: 2.4
  **/
 GArray*
@@ -848,9 +862,10 @@ struct _GRealPtrArray
  * g_ptr_array_index:
  * @array: a #GPtrArray.
  * @index_: the index of the pointer to return.
- * @Returns: the pointer at the given index.
  *
  * Returns the pointer at the given index of the pointer array.
+ *
+ * Returns: the pointer at the given index.
  **/
 
 static void g_ptr_array_maybe_expand (GRealPtrArray *array,
@@ -858,9 +873,10 @@ static void g_ptr_array_maybe_expand (GRealPtrArray *array,
 
 /**
  * g_ptr_array_new:
- * @Returns: the new #GPtrArray.
  *
  * Creates a new #GPtrArray with a reference count of 1.
+ *
+ * Returns: the new #GPtrArray.
  **/
 GPtrArray*
 g_ptr_array_new (void)
@@ -871,12 +887,13 @@ g_ptr_array_new (void)
 /**
  * g_ptr_array_sized_new:
  * @reserved_size: number of pointers preallocated.
- * @Returns: the new #GPtrArray.
  *
  * Creates a new #GPtrArray with @reserved_size pointers preallocated
  * and a reference count of 1. This avoids frequent reallocation, if
  * you are going to add many pointers to the array. Note however that
  * the size of the array is still 0.
+ *
+ * Returns: the new #GPtrArray.
  **/
 GPtrArray*  
 g_ptr_array_sized_new (guint reserved_size)
@@ -1018,8 +1035,6 @@ g_ptr_array_unref (GPtrArray *array)
  * g_ptr_array_free:
  * @array: a #GPtrArray.
  * @free_seg: if %TRUE the actual pointer array is freed as well.
- * @Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL.
- *           The pointer array should be freed using g_free().
  *
  * Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE
  * it frees the memory block holding the elements as well. Pass %FALSE
@@ -1031,6 +1046,9 @@ g_ptr_array_unref (GPtrArray *array)
  * <note><para>If array contents point to dynamically-allocated
  * memory, they should be freed separately if @free_seg is %TRUE and no
  * #GDestroyNotify function has been set for @array.</para></note>
+ *
+ * Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL.
+ *          The pointer array should be freed using g_free().
  **/
 gpointer*
 g_ptr_array_free (GPtrArray *farray,
@@ -1138,12 +1156,13 @@ g_ptr_array_set_size  (GPtrArray *farray,
  * g_ptr_array_remove_index:
  * @array: a #GPtrArray.
  * @index_: the index of the pointer to remove.
- * @Returns: the pointer which was removed.
  *
  * Removes the pointer at the given index from the pointer array. The
  * following elements are moved down one place. If @array has a
  * non-%NULL #GDestroyNotify function it is called for the removed
  * element.
+ *
+ * Returns: the pointer which was removed.
  **/
 gpointer
 g_ptr_array_remove_index (GPtrArray *farray,
@@ -1177,13 +1196,14 @@ g_ptr_array_remove_index (GPtrArray *farray,
  * g_ptr_array_remove_index_fast:
  * @array: a #GPtrArray.
  * @index_: the index of the pointer to remove.
- * @Returns: the pointer which was removed.
  *
  * Removes the pointer at the given index from the pointer array. The
  * last element in the array is used to fill in the space, so this
  * function does not preserve the order of the array. But it is faster
  * than g_ptr_array_remove_index(). If @array has a non-%NULL
  * #GDestroyNotify function it is called for the removed element.
+ *
+ * Returns: the pointer which was removed.
  **/
 gpointer
 g_ptr_array_remove_index_fast (GPtrArray *farray,
@@ -1263,8 +1283,6 @@ g_ptr_array_remove_range (GPtrArray *farray,
  * g_ptr_array_remove:
  * @array: a #GPtrArray.
  * @data: the pointer to remove.
- * @Returns: %TRUE if the pointer is removed. %FALSE if the pointer is
- *           not found in the array.
  *
  * Removes the first occurrence of the given pointer from the pointer
  * array. The following elements are moved down one place. If @array
@@ -1273,6 +1291,9 @@ g_ptr_array_remove_range (GPtrArray *farray,
  *
  * It returns %TRUE if the pointer was removed, or %FALSE if the
  * pointer was not found.
+ *
+ * Returns: %TRUE if the pointer is removed. %FALSE if the pointer is
+ *          not found in the array.
  **/
 gboolean
 g_ptr_array_remove (GPtrArray *farray,
@@ -1299,7 +1320,6 @@ g_ptr_array_remove (GPtrArray *farray,
  * g_ptr_array_remove_fast:
  * @array: a #GPtrArray.
  * @data: the pointer to remove.
- * @Returns: %TRUE if the pointer was found in the array.
  *
  * Removes the first occurrence of the given pointer from the pointer
  * array. The last element in the array is used to fill in the space,
@@ -1309,6 +1329,8 @@ g_ptr_array_remove (GPtrArray *farray,
  *
  * It returns %TRUE if the pointer was removed, or %FALSE if the
  * pointer was not found.
+ *
+ * Returns: %TRUE if the pointer was found in the array.
  **/
 gboolean
 g_ptr_array_remove_fast (GPtrArray *farray,
@@ -1487,9 +1509,10 @@ g_ptr_array_foreach (GPtrArray *array,
 
 /**
  * g_byte_array_new:
- * @Returns: the new #GByteArray.
  *
  * Creates a new #GByteArray with a reference count of 1.
+ *
+ * Returns: the new #GByteArray.
  **/
 GByteArray* g_byte_array_new (void)
 {
@@ -1529,12 +1552,13 @@ g_byte_array_new_take (guint8 *data,
 /**
  * g_byte_array_sized_new:
  * @reserved_size: number of bytes preallocated.
- * @Returns: the new #GByteArray.
  *
  * Creates a new #GByteArray with @reserved_size bytes preallocated.
  * This avoids frequent reallocation, if you are going to add many
  * bytes to the array. Note however that the size of the array is still
  * 0.
+ *
+ * Returns: the new #GByteArray.
  **/
 GByteArray* g_byte_array_sized_new (guint reserved_size)
 {
@@ -1545,13 +1569,14 @@ GByteArray* g_byte_array_sized_new (guint reserved_size)
  * g_byte_array_free:
  * @array: a #GByteArray.
  * @free_segment: if %TRUE the actual byte data is freed as well.
- * @Returns: the element data if @free_segment is %FALSE, otherwise
- *           %NULL.  The element data should be freed using g_free().
  *
  * Frees the memory allocated by the #GByteArray. If @free_segment is
  * %TRUE it frees the actual byte data. If the reference count of
  * @array is greater than one, the #GByteArray wrapper is preserved but
  * the size of @array will be set to zero.
+ *
+ * Returns: the element data if @free_segment is %FALSE, otherwise
+ *          %NULL.  The element data should be freed using g_free().
  **/
 guint8*	    g_byte_array_free     (GByteArray *array,
 			           gboolean    free_segment)
@@ -1627,10 +1652,11 @@ g_byte_array_unref (GByteArray *array)
  * @array: a #GByteArray.
  * @data: the byte data to be added.
  * @len: the number of bytes to add.
- * @Returns: the #GByteArray.
  *
  * Adds the given bytes to the end of the #GByteArray. The array will
  * grow in size automatically if necessary.
+ *
+ * Returns: the #GByteArray.
  **/
 GByteArray* g_byte_array_append   (GByteArray   *array,
 				   const guint8 *data,
@@ -1646,10 +1672,11 @@ GByteArray* g_byte_array_append   (GByteArray   *array,
  * @array: a #GByteArray.
  * @data: the byte data to be added.
  * @len: the number of bytes to add.
- * @Returns: the #GByteArray.
  *
  * Adds the given data to the start of the #GByteArray. The array will
  * grow in size automatically if necessary.
+ *
+ * Returns: the #GByteArray.
  **/
 GByteArray* g_byte_array_prepend  (GByteArray   *array,
 				   const guint8 *data,
@@ -1664,9 +1691,10 @@ GByteArray* g_byte_array_prepend  (GByteArray   *array,
  * g_byte_array_set_size:
  * @array: a #GByteArray.
  * @length: the new size of the #GByteArray.
- * @Returns: the #GByteArray.
  *
  * Sets the size of the #GByteArray, expanding it if necessary.
+ *
+ * Returns: the #GByteArray.
  **/
 GByteArray* g_byte_array_set_size (GByteArray *array,
 				   guint       length)
@@ -1680,10 +1708,11 @@ GByteArray* g_byte_array_set_size (GByteArray *array,
  * g_byte_array_remove_index:
  * @array: a #GByteArray.
  * @index_: the index of the byte to remove.
- * @Returns: the #GByteArray.
  *
  * Removes the byte at the given index from a #GByteArray. The
  * following bytes are moved down one place.
+ *
+ * Returns: the #GByteArray.
  **/
 GByteArray* g_byte_array_remove_index (GByteArray *array,
 				       guint       index_)
@@ -1697,12 +1726,13 @@ GByteArray* g_byte_array_remove_index (GByteArray *array,
  * g_byte_array_remove_index_fast:
  * @array: a #GByteArray.
  * @index_: the index of the byte to remove.
- * @Returns: the #GByteArray.
  *
  * Removes the byte at the given index from a #GByteArray. The last
  * element in the array is used to fill in the space, so this function
  * does not preserve the order of the #GByteArray. But it is faster
  * than g_byte_array_remove_index().
+ *
+ * Returns: the #GByteArray.
  **/
 GByteArray* g_byte_array_remove_index_fast (GByteArray *array,
 					    guint       index_)
@@ -1717,11 +1747,12 @@ GByteArray* g_byte_array_remove_index_fast (GByteArray *array,
  * @array: a @GByteArray.
  * @index_: the index of the first byte to remove.
  * @length: the number of bytes to remove.
- * @Returns: the #GByteArray.
  *
  * Removes the given number of bytes starting at the given index from a
  * #GByteArray.  The following elements are moved to close the gap.
  *
+ * Returns: the #GByteArray.
+ *
  * Since: 2.4
  **/
 GByteArray*
diff --git a/glib/gdataset.c b/glib/gdataset.c
index d3c1cbd..006bdc1 100644
--- a/glib/gdataset.c
+++ b/glib/gdataset.c
@@ -678,10 +678,11 @@ g_datalist_id_set_data_full (GData	  **datalist,
  * g_dataset_id_remove_no_notify:
  * @dataset_location: the location identifying the dataset.
  * @key_id: the #GQuark ID identifying the data element.
- * @Returns: the data previously stored at @key_id, or %NULL if none.
  *
  * Removes an element, without calling its destroy notification
  * function.
+ *
+ * Returns: the data previously stored at @key_id, or %NULL if none.
  **/
 /**
  * g_dataset_remove_no_notify:
@@ -716,10 +717,11 @@ g_dataset_id_remove_no_notify (gconstpointer  dataset_location,
  * g_datalist_id_remove_no_notify:
  * @datalist: a datalist.
  * @key_id: the #GQuark identifying a data element.
- * @Returns: the data previously stored at @key_id, or %NULL if none.
  *
  * Removes an element, without calling its destroy notification
  * function.
+ *
+ * Returns: the data previously stored at @key_id, or %NULL if none.
  **/
 /**
  * g_datalist_remove_no_notify:
@@ -746,19 +748,21 @@ g_datalist_id_remove_no_notify (GData	**datalist,
  * g_dataset_id_get_data:
  * @dataset_location: the location identifying the dataset.
  * @key_id: the #GQuark id to identify the data element.
- * @Returns: the data element corresponding to the #GQuark, or %NULL if
- *           it is not found.
  *
  * Gets the data element corresponding to a #GQuark.
+ *
+ * Returns: the data element corresponding to the #GQuark, or %NULL if
+ *          it is not found.
  **/
 /**
  * g_dataset_get_data:
  * @l: the location identifying the dataset.
  * @k: the string identifying the data element.
- * @Returns: the data element corresponding to the string, or %NULL if
- *           it is not found.
  *
  * Gets the data element corresponding to a string.
+ *
+ * Returns: the data element corresponding to the string, or %NULL if
+ *          it is not found.
  **/
 gpointer
 g_dataset_id_get_data (gconstpointer  dataset_location,
@@ -1004,10 +1008,11 @@ g_datalist_id_replace_data (GData          **datalist,
  * g_datalist_get_data:
  * @datalist: a datalist.
  * @key: the string identifying a data element.
- * @Returns: the data element, or %NULL if it is not found.
  *
  * Gets a data element, using its string identifier. This is slower than
  * g_datalist_id_get_data() because it compares strings.
+ *
+ * Returns: the data element, or %NULL if it is not found.
  **/
 gpointer
 g_datalist_get_data (GData	 **datalist,
diff --git a/glib/giochannel.c b/glib/giochannel.c
index 096fcee..9e9c1cb 100644
--- a/glib/giochannel.c
+++ b/glib/giochannel.c
@@ -689,12 +689,13 @@ g_io_add_watch_full (GIOChannel    *channel,
  * @source: the #GIOChannel event source
  * @condition: the condition which has been satisfied
  * @data: user data set in g_io_add_watch() or g_io_add_watch_full()
- * @Returns: the function should return %FALSE if the event source
- *           should be removed
  *
  * Specifies the type of function passed to g_io_add_watch() or
  * g_io_add_watch_full(), which is called when the requested condition
  * on a #GIOChannel is satisfied.
+ *
+ * Returns: the function should return %FALSE if the event source
+ *          should be removed
  **/
 /**
  * GIOCondition:
diff --git a/glib/giounix.c b/glib/giounix.c
index ee5ae54..517e36b 100644
--- a/glib/giounix.c
+++ b/glib/giounix.c
@@ -584,7 +584,6 @@ g_io_channel_new_file (const gchar *filename,
 /**
  * g_io_channel_unix_new:
  * @fd: a file descriptor.
- * @Returns: a new #GIOChannel.
  *
  * Creates a new #GIOChannel given a file descriptor. On UNIX systems
  * this works for plain files, pipes, and sockets.
@@ -606,6 +605,8 @@ g_io_channel_new_file (const gchar *filename,
  * in case the argument you pass to this function happens to be both a
  * valid file descriptor and socket. If that happens a warning is
  * issued, and GLib assumes that it is the file descriptor you mean.
+ *
+ * Returns: a new #GIOChannel.
  **/
 GIOChannel *
 g_io_channel_unix_new (gint fd)
@@ -639,12 +640,13 @@ g_io_channel_unix_new (gint fd)
 /**
  * g_io_channel_unix_get_fd:
  * @channel: a #GIOChannel, created with g_io_channel_unix_new().
- * @Returns: the file descriptor of the #GIOChannel.
  *
  * Returns the file descriptor of the #GIOChannel.
  *
  * On Windows this function returns the file descriptor or socket of
  * the #GIOChannel.
+ *
+ * Returns: the file descriptor of the #GIOChannel.
  **/
 gint
 g_io_channel_unix_get_fd (GIOChannel *channel)
diff --git a/glib/giowin32.c b/glib/giowin32.c
index d39a4b2..10667ec 100644
--- a/glib/giowin32.c
+++ b/glib/giowin32.c
@@ -1972,12 +1972,13 @@ static GIOFuncs win32_channel_sock_funcs = {
 /**
  * g_io_channel_win32_new_messages:
  * @hwnd: a window handle.
- * @Returns: a new #GIOChannel.
  *
  * Creates a new #GIOChannel given a window handle on Windows.
  *
  * This function creates a #GIOChannel that can be used to poll for
  * Windows messages for the window in question.
+ *
+ * Returns: a new #GIOChannel.
  **/
 GIOChannel *
 #if GLIB_SIZEOF_VOID_P == 8
@@ -2045,7 +2046,6 @@ g_io_channel_win32_new_fd_internal (gint             fd,
 /**
  * g_io_channel_win32_new_fd:
  * @fd: a C library file descriptor.
- * @Returns: a new #GIOChannel.
  *
  * Creates a new #GIOChannel given a file descriptor on Windows. This
  * works for file descriptors from the C runtime.
@@ -2069,6 +2069,8 @@ g_io_channel_win32_new_fd_internal (gint             fd,
  * thread. Your code should call only g_io_channel_read().
  *
  * This function is available only in GLib on Windows.
+ *
+ * Returns: a new #GIOChannel.
  **/
 GIOChannel *
 g_io_channel_win32_new_fd (gint fd)
@@ -2095,7 +2097,6 @@ g_io_channel_win32_get_fd (GIOChannel *channel)
 /**
  * g_io_channel_win32_new_socket:
  * @socket: a Winsock socket
- * @Returns: a new #GIOChannel
  *
  * Creates a new #GIOChannel given a socket on Windows.
  *
@@ -2105,6 +2106,8 @@ g_io_channel_win32_get_fd (GIOChannel *channel)
  * Polling a #GSource created to watch a channel for a socket puts the
  * socket in non-blocking mode. This is a side-effect of the
  * implementation and unavoidable.
+ *
+ * Returns: a new #GIOChannel
  **/
 GIOChannel *
 g_io_channel_win32_new_socket (int socket)
diff --git a/glib/glist.c b/glib/glist.c
index 1c4f9e4..f4905f3 100644
--- a/glib/glist.c
+++ b/glib/glist.c
@@ -97,18 +97,20 @@
 /**
  * g_list_previous:
  * @list: an element in a #GList.
- * @Returns: the previous element, or %NULL if there are no previous
- *           elements.
  *
  * A convenience macro to get the previous element in a #GList.
+ *
+ * Returns: the previous element, or %NULL if there are no previous
+ *          elements.
  **/
 
 /**
  * g_list_next:
  * @list: an element in a #GList.
- * @Returns: the next element, or %NULL if there are no more elements.
  *
  * A convenience macro to get the next element in a #GList.
+ *
+ * Returns: the next element, or %NULL if there are no more elements.
  **/
 
 #define _g_list_alloc()         g_slice_new (GList)
@@ -117,11 +119,12 @@
 
 /**
  * g_list_alloc:
- * @Returns: a pointer to the newly-allocated #GList element.
  *
  * Allocates space for one #GList element. It is called by
  * g_list_append(), g_list_prepend(), g_list_insert() and
  * g_list_insert_sorted() and so is rarely used on its own.
+ *
+ * Returns: a pointer to the newly-allocated #GList element.
  **/
 GList*
 g_list_alloc (void)
@@ -1126,13 +1129,14 @@ g_list_sort_real (GList    *list,
  * GCompareFunc:
  * @a: a value.
  * @b: a value to compare with.
- * @Returns: negative value if @a &lt; @b; zero if @a = @b; positive
- *           value if @a > @b.
  *
  * Specifies the type of a comparison function used to compare two
  * values.  The function should return a negative integer if the first
  * value comes before the second, 0 if they are equal, or a positive
  * integer if the first value comes after the second.
+ *
+ * Returns: negative value if @a &lt; @b; zero if @a = @b; positive
+ *          value if @a > @b.
  **/
 GList *
 g_list_sort (GList        *list,
@@ -1158,13 +1162,14 @@ g_list_sort (GList        *list,
  * @a: a value.
  * @b: a value to compare with.
  * @user_data: user data to pass to comparison function.
- * @Returns: negative value if @a &lt; @b; zero if @a = @b; positive
- *           value if @a > @b.
  *
  * Specifies the type of a comparison function used to compare two
  * values.  The function should return a negative integer if the first
  * value comes before the second, 0 if they are equal, or a positive
  * integer if the first value comes after the second.
+ *
+ * Returns: negative value if @a &lt; @b; zero if @a = @b; positive
+ *          value if @a > @b.
  **/
 GList *
 g_list_sort_with_data (GList            *list,
diff --git a/glib/gnode.c b/glib/gnode.c
index b2c3226..80cc44b 100644
--- a/glib/gnode.c
+++ b/glib/gnode.c
@@ -840,12 +840,13 @@ g_node_depth_traverse_level (GNode             *node,
  * GNodeTraverseFunc:
  * @node: a #GNode.
  * @data: user data passed to g_node_traverse().
- * @Returns: %TRUE to stop the traversal.
  *
  * Specifies the type of function passed to g_node_traverse(). The
  * function is called with each of the nodes visited, together with the
  * user data passed to g_node_traverse(). If the function returns
  * %TRUE, then the traversal is stopped.
+ *
+ * Returns: %TRUE to stop the traversal.
  **/
 void
 g_node_traverse (GNode		  *root,
diff --git a/glib/gpattern.c b/glib/gpattern.c
index bc0cc71..c638086 100644
--- a/glib/gpattern.c
+++ b/glib/gpattern.c
@@ -168,7 +168,6 @@ g_pattern_ph_match (const gchar *match_pattern,
  *                 <emphasis>not</emphasis> g_utf8_strlen())
  * @string: the UTF-8 encoded string to match
  * @string_reversed: (allow-none): the reverse of @string or %NULL
- * @Returns: %TRUE if @string matches @pspec
  *
  * Matches a string against a compiled pattern. Passing the correct
  * length of the string given is mandatory. The reversed string can be
@@ -188,6 +187,8 @@ g_pattern_ph_match (const gchar *match_pattern,
  * only if the string doesn't contain any multibyte characters. GLib
  * offers the g_utf8_strreverse() function to reverse UTF-8 encoded
  * strings.
+ *
+ * Returns: %TRUE if @string matches @pspec
  **/
 gboolean
 g_pattern_match (GPatternSpec *pspec,
@@ -245,9 +246,10 @@ g_pattern_match (GPatternSpec *pspec,
 /**
  * g_pattern_spec_new:
  * @pattern: a zero-terminated UTF-8 encoded string
- * @Returns: a newly-allocated #GPatternSpec
  *
  * Compiles a pattern to a #GPatternSpec.
+ *
+ * Returns: a newly-allocated #GPatternSpec
  **/
 GPatternSpec*
 g_pattern_spec_new (const gchar *pattern)
@@ -376,10 +378,11 @@ g_pattern_spec_free (GPatternSpec *pspec)
  * g_pattern_spec_equal:
  * @pspec1: a #GPatternSpec
  * @pspec2: another #GPatternSpec
- * @Returns: Whether the compiled patterns are equal
  *
  * Compares two compiled pattern specs and returns whether they will
  * match the same set of strings.
+ *
+ * Returns: Whether the compiled patterns are equal
  **/
 gboolean
 g_pattern_spec_equal (GPatternSpec *pspec1,
@@ -397,11 +400,12 @@ g_pattern_spec_equal (GPatternSpec *pspec1,
  * g_pattern_match_string:
  * @pspec: a #GPatternSpec
  * @string: the UTF-8 encoded string to match
- * @Returns: %TRUE if @string matches @pspec
  *
  * Matches a string against a compiled pattern. If the string is to be
  * matched against more than one pattern, consider using
  * g_pattern_match() instead while supplying the reversed string.
+ *
+ * Returns: %TRUE if @string matches @pspec
  **/
 gboolean
 g_pattern_match_string (GPatternSpec *pspec,
@@ -417,12 +421,13 @@ g_pattern_match_string (GPatternSpec *pspec,
  * g_pattern_match_simple:
  * @pattern: the UTF-8 encoded pattern
  * @string: the UTF-8 encoded string to match
- * @Returns: %TRUE if @string matches @pspec
  *
  * Matches a string against a pattern given as a string. If this
  * function is to be called in a loop, it's more efficient to compile
  * the pattern once with g_pattern_spec_new() and call
  * g_pattern_match_string() repeatedly.
+ *
+ * Returns: %TRUE if @string matches @pspec
  **/
 gboolean
 g_pattern_match_simple (const gchar *pattern,
diff --git a/glib/grand.c b/glib/grand.c
index 4d6a0a6..1485c2e 100644
--- a/glib/grand.c
+++ b/glib/grand.c
@@ -404,10 +404,11 @@ g_rand_set_seed_array (GRand* rand, const guint32 *seed, guint seed_length)
 /**
  * g_rand_boolean:
  * @rand_: a #GRand.
- * @Returns: a random #gboolean.
  *
  * Returns a random #gboolean from @rand_. This corresponds to a
  * unbiased coin toss.
+ *
+ * Returns: a random #gboolean.
  **/
 /**
  * g_rand_int:
@@ -585,9 +586,10 @@ g_rand_double_range (GRand* rand, gdouble begin, gdouble end)
 
 /**
  * g_random_boolean:
- * @Returns: a random #gboolean.
  *
  * Returns a random #gboolean. This corresponds to a unbiased coin toss.
+ *
+ * Returns: a random #gboolean.
  **/
 /**
  * g_random_int:
diff --git a/glib/gsequence.c b/glib/gsequence.c
index ee3da34..6004120 100644
--- a/glib/gsequence.c
+++ b/glib/gsequence.c
@@ -79,13 +79,14 @@
  * @a: a #GSequenceIter
  * @b: a #GSequenceIter
  * @data: user data
- * @Returns: zero if the iterators are equal, a negative value if @a
- *           comes before @b, and a positive value if @b comes before
- *           @a.
  *
  * A #GSequenceIterCompareFunc is a function used to compare iterators.
  * It must return zero if the iterators compare equal, a negative value
  * if @a comes before @b, and a positive value if @b comes before @a.
+ *
+ * Returns: zero if the iterators are equal, a negative value if @a
+ *          comes before @b, and a positive value if @b comes before
+ *          @a.
  **/
 
 typedef struct _GSequenceNode GSequenceNode;
diff --git a/glib/gslist.c b/glib/gslist.c
index 1b047ec..7cec285 100644
--- a/glib/gslist.c
+++ b/glib/gslist.c
@@ -98,9 +98,10 @@
 /**
  * g_slist_next:
  * @slist: an element in a #GSList.
- * @Returns: the next element, or %NULL if there are no more elements.
  *
  * A convenience macro to get the next element in a #GSList.
+ *
+ * Returns: the next element, or %NULL if there are no more elements.
  **/
 
 #define _g_slist_alloc0()       g_slice_new0 (GSList)
@@ -109,11 +110,12 @@
 
 /**
  * g_slist_alloc:
- * @Returns: a pointer to the newly-allocated #GSList element.
  *
  * Allocates space for one #GSList element. It is called by the
  * g_slist_append(), g_slist_prepend(), g_slist_insert() and
  * g_slist_insert_sorted() functions and so is rarely used on its own.
+ *
+ * Returns: a pointer to the newly-allocated #GSList element.
  **/
 GSList*
 g_slist_alloc (void)
diff --git a/glib/gthread.c b/glib/gthread.c
index ee87574..d3a924a 100644
--- a/glib/gthread.c
+++ b/glib/gthread.c
@@ -215,10 +215,11 @@
 /**
  * G_TRYLOCK:
  * @name: the name of the lock
- * @Returns: %TRUE, if the lock could be locked.
  *
  * Works like g_mutex_trylock(), but for a lock defined with
  * #G_LOCK_DEFINE.
+ *
+ * Returns: %TRUE, if the lock could be locked.
  */
 
 /**
diff --git a/glib/gtimer.c b/glib/gtimer.c
index 6e962b4..a45c3cf 100644
--- a/glib/gtimer.c
+++ b/glib/gtimer.c
@@ -82,10 +82,11 @@ struct _GTimer
 
 /**
  * g_timer_new:
- * @Returns: a new #GTimer.
  *
  * Creates a new timer, and starts timing (i.e. g_timer_start() is
  * implicitly called for you).
+ *
+ * Returns: a new #GTimer.
  **/
 GTimer*
 g_timer_new (void)
@@ -204,8 +205,6 @@ g_timer_continue (GTimer *timer)
  * @microseconds: return location for the fractional part of seconds
  *                elapsed, in microseconds (that is, the total number
  *                of microseconds elapsed, modulo 1000000), or %NULL
- * @Returns: seconds elapsed as a floating point value, including any
- *           fractional part.
  *
  * If @timer has been started but not stopped, obtains the time since
  * the timer was started. If @timer has been stopped, obtains the
@@ -213,6 +212,9 @@ g_timer_continue (GTimer *timer)
  * stopped. The return value is the number of seconds elapsed,
  * including any fractional part. The @microseconds out parameter is
  * essentially useless.
+ *
+ * Returns: seconds elapsed as a floating point value, including any
+ *          fractional part.
  **/
 gdouble
 g_timer_elapsed (GTimer *timer,
diff --git a/glib/gtree.c b/glib/gtree.c
index a559a61..c6b3eea 100644
--- a/glib/gtree.c
+++ b/glib/gtree.c
@@ -945,12 +945,13 @@ g_tree_foreach (GTree         *tree,
  * @key: a key of a #GTree node.
  * @value: the value corresponding to the key.
  * @data: user data passed to g_tree_traverse().
- * @Returns: %TRUE to stop the traversal.
  *
  * Specifies the type of function passed to g_tree_traverse(). It is
  * passed the key and value of each node, together with the @user_data
  * parameter passed to g_tree_traverse(). If the function returns
  * %TRUE, the traversal is stopped.
+ *
+ * Returns: %TRUE to stop the traversal.
  **/
 /**
  * GTraverseType:
diff --git a/glib/gvariant-parser.c b/glib/gvariant-parser.c
index 0662be3..e2e85ab 100644
--- a/glib/gvariant-parser.c
+++ b/glib/gvariant-parser.c
@@ -2303,7 +2303,6 @@ parse (TokenStream  *stream,
  * @limit: (allow-none): a pointer to the end of @text, or %NULL
  * @endptr: (allow-none): a location to store the end pointer, or %NULL
  * @error: (allow-none): a pointer to a %NULL #GError pointer, or %NULL
- * @Returns: a reference to a #GVariant, or %NULL
  *
  * Parses a #GVariant from a text representation.
  *
@@ -2335,6 +2334,8 @@ parse (TokenStream  *stream,
  *
  * Officially, the language understood by the parser is "any string
  * produced by g_variant_print()".
+ *
+ * Returns: a reference to a #GVariant, or %NULL
  **/
 GVariant *
 g_variant_parse (const GVariantType  *type,