From 59a24ab5a3ffff7d2cd36a1b392b49cc4024c29d Mon Sep 17 00:00:00 2001 From: Robert Ancell Date: Wed, 31 Oct 2012 14:56:00 +1300 Subject: [PATCH] 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 5c3343403..44594bfdb 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 4968c3239..5a593656d 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 (not 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 * (not 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 7f7d7befb..fb5ab61c7 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 a8b2c4d1c..7f6fdffac 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 5e25ce893..a98fc9587 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 b88ae7b82..bdcbc935d 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 = &g_array_index (events, EDayViewEvent, 3); * * + * + * 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) * * If array elements contain dynamically-allocated memory, * they should be freed separately. + * + * 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, * 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. + * + * 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, * 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. + * + * 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. * * 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. + * + * 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) * 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. + * + * 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 d3c1cbd1f..006bdc18a 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 096fcee73..9e9c1cb66 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 ee5ae54d1..517e36bdd 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 d39a4b2ef..10667ece5 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 1c4f9e42f..f4905f31a 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 < @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 < @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 < @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 < @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 b2c3226cd..80cc44bf2 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 bc0cc714c..c638086ce 100644 --- a/glib/gpattern.c +++ b/glib/gpattern.c @@ -168,7 +168,6 @@ g_pattern_ph_match (const gchar *match_pattern, * not 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 4d6a0a621..1485c2ecb 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 ee3da34e0..6004120e4 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 1b047ec4a..7cec28526 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 ee875746b..d3a924ac0 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 6e962b462..a45c3cff0 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 a559a6171..c6b3eea2a 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 0662be38f..e2e85abb0 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,