luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-08 18:36:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
https://bugzilla.gnome.org/show_bug.cgi?id=673229
This commit is contained in:
Robert Ancell 2012-10-31 14:56:00 +13:00
parent 4447d5ce11
commit 59a24ab5a3
20 changed files with 200 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
gio/gvdb/gvdb-reader.c
View File

@ -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)

6
glib/deprecated/gcache.c
View File

@ -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,

20
glib/deprecated/gcompletion.c
View File

@ -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*

18
glib/deprecated/grel.c
View File

@ -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

23
glib/deprecated/gthread-deprecated.c
View File

@ -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

101
glib/garray.c
View File

@ -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*

19
glib/gdataset.c
View File

@ -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,

5
glib/giochannel.c
View File

@ -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:

6
glib/giounix.c
View File

@ -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)

9
glib/giowin32.c
View File

@ -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)

21
glib/glist.c
View File

@ -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,

3
glib/gnode.c
View File

@ -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,

15
glib/gpattern.c
View File

@ -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,

6
glib/grand.c
View File

@ -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:

7
glib/gsequence.c
View File

@ -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;

6
glib/gslist.c
View File

@ -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)

3
glib/gthread.c
View File

@ -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.
*/
/**

8
glib/gtimer.c
View File

@ -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,

3
glib/gtree.c
View File

@ -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:

3
glib/gvariant-parser.c
View File

@ -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,