Commit 59a24ab5 authored by Robert Ancell's avatar Robert Ancell

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

https://bugzilla.gnome.org/show_bug.cgi?id=673229
parent 4447d5ce
......@@ -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)
......
......@@ -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,
......
......@@ -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*
......
......@@ -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
......
......@@ -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
......
......@@ -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