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

https://bugzilla.gnome.org/show_bug.cgi?id=673229
2025-10-31 08:22:16 +01:00 · 2012-10-31 14:56:00 +13:00
parent 4447d5ce11
commit 59a24ab5a3
20 changed files with 200 additions and 109 deletions
--- 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)
--- 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,
--- 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* 
--- 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
--- 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
--- 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*
--- 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,
--- 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:
--- 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)
--- 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)
--- 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,
--- 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,
--- 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,
--- 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:
--- 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;
--- 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)
--- 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.
 */

 /**
--- 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,
--- 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:
--- 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,