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, ...@@ -187,7 +187,6 @@ new_from_data (const void *data,
* @filename: the path to the hash file * @filename: the path to the hash file
* @trusted: if the contents of @filename are trusted * @trusted: if the contents of @filename are trusted
* @error: %NULL, or a pointer to a %NULL #GError * @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 * Creates a new #GvdbTable from the contents of the file found at
* @filename. * @filename.
...@@ -201,6 +200,8 @@ new_from_data (const void *data, ...@@ -201,6 +200,8 @@ new_from_data (const void *data,
* *
* You should call gvdb_table_unref() on the return result when you no * You should call gvdb_table_unref() on the return result when you no
* longer require it. * longer require it.
*
* Returns: a new #GvdbTable
**/ **/
GvdbTable * GvdbTable *
gvdb_table_new (const gchar *filename, gvdb_table_new (const gchar *filename,
...@@ -230,7 +231,6 @@ gvdb_table_new (const gchar *filename, ...@@ -230,7 +231,6 @@ gvdb_table_new (const gchar *filename,
* @user_data: User supplied data that owns @data * @user_data: User supplied data that owns @data
* @ref: Ref function for @user_data * @ref: Ref function for @user_data
* @unref: Unref function for @user_data * @unref: Unref function for @user_data
* @returns: a new #GvdbTable
* *
* Creates a new #GvdbTable from the data in @data. * Creates a new #GvdbTable from the data in @data.
* *
...@@ -239,6 +239,8 @@ gvdb_table_new (const gchar *filename, ...@@ -239,6 +239,8 @@ gvdb_table_new (const gchar *filename,
* *
* You should call gvdb_table_unref() on the return result when you no * You should call gvdb_table_unref() on the return result when you no
* longer require it. * longer require it.
*
* Returns: a new #GvdbTable
**/ **/
GvdbTable * GvdbTable *
gvdb_table_new_from_data (const void *data, gvdb_table_new_from_data (const void *data,
...@@ -381,7 +383,6 @@ gvdb_table_list_from_item (GvdbTable *table, ...@@ -381,7 +383,6 @@ gvdb_table_list_from_item (GvdbTable *table,
* gvdb_table_list: * gvdb_table_list:
* @file: a #GvdbTable * @file: a #GvdbTable
* @key: a string * @key: a string
* @returns: a %NULL-terminated string array
* *
* List all of the keys that appear below @key. The nesting of keys * 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 * within the hash file is defined by the program that created the hash
...@@ -394,6 +395,8 @@ gvdb_table_list_from_item (GvdbTable *table, ...@@ -394,6 +395,8 @@ gvdb_table_list_from_item (GvdbTable *table,
* *
* You should call g_strfreev() on the return result when you no longer * You should call g_strfreev() on the return result when you no longer
* require it. * require it.
*
* Returns: a %NULL-terminated string array
**/ **/
gchar ** gchar **
gvdb_table_list (GvdbTable *file, gvdb_table_list (GvdbTable *file,
...@@ -444,12 +447,13 @@ gvdb_table_list (GvdbTable *file, ...@@ -444,12 +447,13 @@ gvdb_table_list (GvdbTable *file,
* gvdb_table_has_value: * gvdb_table_has_value:
* @file: a #GvdbTable * @file: a #GvdbTable
* @key: a string * @key: a string
* @returns: %TRUE if @key is in the table
* *
* Checks for a value named @key in @file. * Checks for a value named @key in @file.
* *
* Note: this function does not consider non-value nodes (other hash * Note: this function does not consider non-value nodes (other hash
* tables, for example). * tables, for example).
*
* Returns: %TRUE if @key is in the table
**/ **/
gboolean gboolean
gvdb_table_has_value (GvdbTable *file, gvdb_table_has_value (GvdbTable *file,
...@@ -485,7 +489,6 @@ gvdb_table_value_from_item (GvdbTable *table, ...@@ -485,7 +489,6 @@ gvdb_table_value_from_item (GvdbTable *table,
* gvdb_table_get_value: * gvdb_table_get_value:
* @file: a #GvdbTable * @file: a #GvdbTable
* @key: a string * @key: a string
* @returns: a #GVariant, or %NULL
* *
* Looks up a value named @key in @file. * Looks up a value named @key in @file.
* *
...@@ -495,6 +498,8 @@ gvdb_table_value_from_item (GvdbTable *table, ...@@ -495,6 +498,8 @@ gvdb_table_value_from_item (GvdbTable *table,
* *
* You should call g_variant_unref() on the return result when you no * You should call g_variant_unref() on the return result when you no
* longer require it. * longer require it.
*
* Returns: a #GVariant, or %NULL
**/ **/
GVariant * GVariant *
gvdb_table_get_value (GvdbTable *file, gvdb_table_get_value (GvdbTable *file,
...@@ -524,12 +529,13 @@ gvdb_table_get_value (GvdbTable *file, ...@@ -524,12 +529,13 @@ gvdb_table_get_value (GvdbTable *file,
* gvdb_table_get_raw_value: * gvdb_table_get_raw_value:
* @table: a #GvdbTable * @table: a #GvdbTable
* @key: a string * @key: a string
* @returns: a #GVariant, or %NULL
* *
* Looks up a value named @key in @file. * Looks up a value named @key in @file.
* *
* This call is equivalent to gvdb_table_get_value() except that it * This call is equivalent to gvdb_table_get_value() except that it
* never byteswaps the value. * never byteswaps the value.
*
* Returns: a #GVariant, or %NULL
**/ **/
GVariant * GVariant *
gvdb_table_get_raw_value (GvdbTable *table, gvdb_table_get_raw_value (GvdbTable *table,
...@@ -547,7 +553,6 @@ gvdb_table_get_raw_value (GvdbTable *table, ...@@ -547,7 +553,6 @@ gvdb_table_get_raw_value (GvdbTable *table,
* gvdb_table_get_table: * gvdb_table_get_table:
* @file: a #GvdbTable * @file: a #GvdbTable
* @key: a string * @key: a string
* @returns: a new #GvdbTable, or %NULL
* *
* Looks up the hash table named @key in @file. * Looks up the hash table named @key in @file.
* *
...@@ -561,6 +566,8 @@ gvdb_table_get_raw_value (GvdbTable *table, ...@@ -561,6 +566,8 @@ gvdb_table_get_raw_value (GvdbTable *table,
* *
* You should call gvdb_table_unref() on the return result when you no * You should call gvdb_table_unref() on the return result when you no
* longer require it. * longer require it.
*
* Returns: a new #GvdbTable, or %NULL
**/ **/
GvdbTable * GvdbTable *
gvdb_table_get_table (GvdbTable *file, gvdb_table_get_table (GvdbTable *file,
...@@ -592,9 +599,10 @@ gvdb_table_get_table (GvdbTable *file, ...@@ -592,9 +599,10 @@ gvdb_table_get_table (GvdbTable *file,
/** /**
* gvdb_table_ref: * gvdb_table_ref:
* @file: a #GvdbTable * @file: a #GvdbTable
* @returns: a new reference on @file
* *
* Increases the reference count on @file. * Increases the reference count on @file.
*
* Returns: a new reference on @file
**/ **/
GvdbTable * GvdbTable *
gvdb_table_ref (GvdbTable *file) gvdb_table_ref (GvdbTable *file)
...@@ -626,13 +634,14 @@ gvdb_table_unref (GvdbTable *file) ...@@ -626,13 +634,14 @@ gvdb_table_unref (GvdbTable *file)
/** /**
* gvdb_table_is_valid: * gvdb_table_is_valid:
* @table: a #GvdbTable * @table: a #GvdbTable
* @returns: %TRUE if @table is still valid
* *
* Checks if the 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 * 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 * has been replaced. The appropriate action is typically to reopen the
* file. * file.
*
* Returns: %TRUE if @table is still valid
**/ **/
gboolean gboolean
gvdb_table_is_valid (GvdbTable *table) gvdb_table_is_valid (GvdbTable *table)
......
...@@ -136,11 +136,12 @@ g_cache_node_destroy (GCacheNode *node) ...@@ -136,11 +136,12 @@ g_cache_node_destroy (GCacheNode *node)
/** /**
* GCacheNewFunc: * GCacheNewFunc:
* @key: a #GCache key * @key: a #GCache key
* @Returns: a new #GCache value corresponding to the key.
* *
* Specifies the type of the @value_new_func function passed to * Specifies the type of the @value_new_func function passed to
* g_cache_new(). It is passed a #GCache key and should create the * g_cache_new(). It is passed a #GCache key and should create the
* value corresponding to the key. * value corresponding to the key.
*
* Returns: a new #GCache value corresponding to the key.
*/ */
/** /**
...@@ -157,12 +158,13 @@ g_cache_node_destroy (GCacheNode *node) ...@@ -157,12 +158,13 @@ g_cache_node_destroy (GCacheNode *node)
* GCacheDupFunc: * GCacheDupFunc:
* @value: the #GCache key to destroy (<emphasis>not</emphasis> a * @value: the #GCache key to destroy (<emphasis>not</emphasis> a
* #GCache value as it seems) * #GCache value as it seems)
* @Returns: a copy of the #GCache key
* *
* Specifies the type of the @key_dup_func function passed to * Specifies the type of the @key_dup_func function passed to
* g_cache_new(). The function is passed a key * g_cache_new(). The function is passed a key
* (<emphasis>not</emphasis> a value as the prototype implies) and * (<emphasis>not</emphasis> a value as the prototype implies) and
* should return a duplicate of the key. * should return a duplicate of the key.
*
* Returns: a copy of the #GCache key
*/ */
GCache* GCache*
g_cache_new (GCacheNewFunc value_new_func, g_cache_new (GCacheNewFunc value_new_func,
......
...@@ -86,11 +86,12 @@ ...@@ -86,11 +86,12 @@
/** /**
* GCompletionFunc: * GCompletionFunc:
* @Param1: the completion item. * @Param1: the completion item.
* @Returns: the string corresponding to the item.
* *
* Specifies the type of the function passed to g_completion_new(). It * Specifies the type of the function passed to g_completion_new(). It
* should return the string corresponding to the given target item. * should return the string corresponding to the given target item.
* This is used when you use data structures as #GCompletion items. * This is used when you use data structures as #GCompletion items.
*
* Returns: the string corresponding to the item.
**/ **/
/** /**
...@@ -98,14 +99,15 @@ ...@@ -98,14 +99,15 @@
* @s1: string to compare with @s2. * @s1: string to compare with @s2.
* @s2: string to compare with @s1. * @s2: string to compare with @s1.
* @n: maximal number of bytes to compare. * @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 * Specifies the type of the function passed to
* g_completion_set_compare(). This is used when you use strings as * g_completion_set_compare(). This is used when you use strings as
* #GCompletion items. * #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, static void completion_check_cache (GCompletion* cmp,
...@@ -116,9 +118,10 @@ 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 * @func: the function to be called to return the string representing
* an item in the #GCompletion, or %NULL if strings are going to * an item in the #GCompletion, or %NULL if strings are going to
* be used as the #GCompletion items. * be used as the #GCompletion items.
* @Returns: the new #GCompletion.
* *
* Creates a new #GCompletion. * Creates a new #GCompletion.
*
* Returns: the new #GCompletion.
**/ **/
GCompletion* GCompletion*
g_completion_new (GCompletionFunc func) g_completion_new (GCompletionFunc func)
...@@ -336,12 +339,13 @@ g_completion_complete_utf8 (GCompletion *cmp, ...@@ -336,12 +339,13 @@ g_completion_complete_utf8 (GCompletion *cmp,
* common to all items that matched @prefix, or %NULL if * common to all items that matched @prefix, or %NULL if
* no items matched @prefix. This string should be freed * no items matched @prefix. This string should be freed
* when no longer needed. * 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 * Attempts to complete the string @prefix using the #GCompletion
* target items. * 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 * Deprecated: 2.26: Rarely used API
**/ **/
GList* GList*
......
...@@ -185,11 +185,12 @@ tuple_equal (gint fields) ...@@ -185,11 +185,12 @@ tuple_equal (gint fields)
/** /**
* g_relation_new: * g_relation_new:
* @fields: the number of fields. * @fields: the number of fields.
* @Returns: a new #GRelation.
* *
* Creates a new #GRelation with the given number of fields. Note that * Creates a new #GRelation with the given number of fields. Note that
* currently the number of fields must be 2. * currently the number of fields must be 2.
* *
* Returns: a new #GRelation.
*
* Deprecated: 2.26: Rarely used API * Deprecated: 2.26: Rarely used API
**/ **/
GRelation* GRelation*
...@@ -375,11 +376,12 @@ g_relation_delete_tuple (gpointer tuple_key, ...@@ -375,11 +376,12 @@ g_relation_delete_tuple (gpointer tuple_key,
* @relation: a #GRelation. * @relation: a #GRelation.
* @key: the value to compare with. * @key: the value to compare with.
* @field: the field of each record to match. * @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 * Deletes any records from a #GRelation that have the given key value
* in the given field. * in the given field.
* *
* Returns: the number of records deleted.
*
* Deprecated: 2.26: Rarely used API * Deprecated: 2.26: Rarely used API
**/ **/
gint gint
...@@ -439,12 +441,13 @@ g_relation_select_tuple (gpointer tuple_key, ...@@ -439,12 +441,13 @@ g_relation_select_tuple (gpointer tuple_key,
* @relation: a #GRelation. * @relation: a #GRelation.
* @key: the value to compare with. * @key: the value to compare with.
* @field: the field of each record to match. * @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 * Returns all of the tuples which have the given key in the given
* field. Use g_tuples_index() to access the returned records. The * field. Use g_tuples_index() to access the returned records. The
* returned records should be freed with g_tuples_destroy(). * returned records should be freed with g_tuples_destroy().
* *
* Returns: the records (tuples) that matched.
*
* Deprecated: 2.26: Rarely used API * Deprecated: 2.26: Rarely used API
**/ **/
GTuples* GTuples*
...@@ -486,11 +489,12 @@ g_relation_select (GRelation *relation, ...@@ -486,11 +489,12 @@ g_relation_select (GRelation *relation,
* @relation: a #GRelation. * @relation: a #GRelation.
* @key: the value to compare with. * @key: the value to compare with.
* @field: the field of each record to match. * @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 * Returns the number of tuples in a #GRelation that have the given
* value in the given field. * value in the given field.
* *
* Returns: the number of matches.
*
* Deprecated: 2.26: Rarely used API * Deprecated: 2.26: Rarely used API
**/ **/
gint gint
...@@ -520,12 +524,13 @@ g_relation_count (GRelation *relation, ...@@ -520,12 +524,13 @@ g_relation_count (GRelation *relation,
* @relation: a #GRelation. * @relation: a #GRelation.
* @...: the fields of the record to compare. The number must match * @...: the fields of the record to compare. The number must match
* the number of fields in the #GRelation. * 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 * Returns %TRUE if a record with the given values exists in a
* #GRelation. Note that the values are compared directly, so that, for * #GRelation. Note that the values are compared directly, so that, for
* example, two copies of the same string will not match. * example, two copies of the same string will not match.
* *
* Returns: %TRUE if a record matches.
*
* Deprecated: 2.26: Rarely used API * Deprecated: 2.26: Rarely used API
**/ **/
gboolean gboolean
...@@ -578,12 +583,13 @@ g_tuples_destroy (GTuples *tuples0) ...@@ -578,12 +583,13 @@ g_tuples_destroy (GTuples *tuples0)
* @tuples: the tuple data, returned by g_relation_select(). * @tuples: the tuple data, returned by g_relation_select().
* @index_: the index of the record. * @index_: the index of the record.
* @field: the field to return. * @field: the field to return.
* @Returns: the field of the record.
* *
* Gets a field from the records returned by g_relation_select(). It * Gets a field from the records returned by g_relation_select(). It
* returns the given field of the record at the given index. The * returns the given field of the record at the given index. The
* returned value should not be changed. * returned value should not be changed.
* *
* Returns: the field of the record.
*
* Deprecated: 2.26: Rarely used API * Deprecated: 2.26: Rarely used API
**/ **/
gpointer gpointer
......
...@@ -351,10 +351,11 @@ g_thread_create (GThreadFunc func, ...@@ -351,10 +351,11 @@ g_thread_create (GThreadFunc func,
* @bound: ignored * @bound: ignored
* @priority: ignored * @priority: ignored
* @error: return location for error. * @error: return location for error.
* @Returns: the new #GThread on success.
* *
* This function creates a new thread. * This function creates a new thread.
* *
* Returns: the new #GThread on success.
*
* Deprecated:2.32: The @bound and @priority arguments are now ignored. * Deprecated:2.32: The @bound and @priority arguments are now ignored.
* Use g_thread_new(). * Use g_thread_new().
*/ */
...@@ -501,12 +502,13 @@ g_static_mutex_init (GStaticMutex *mutex) ...@@ -501,12 +502,13 @@ g_static_mutex_init (GStaticMutex *mutex)
/** /**
* g_static_mutex_get_mutex: * g_static_mutex_get_mutex:
* @mutex: a #GStaticMutex. * @mutex: a #GStaticMutex.
* @Returns: the #GMutex corresponding to @mutex.
* *
* For some operations (like g_cond_wait()) you must have a #GMutex * For some operations (like g_cond_wait()) you must have a #GMutex
* instead of a #GStaticMutex. This function will return the * instead of a #GStaticMutex. This function will return the
* corresponding #GMutex for @mutex. * corresponding #GMutex for @mutex.
* *
* Returns: the #GMutex corresponding to @mutex.
*
* Deprecated: 2.32: Just use a #GMutex * Deprecated: 2.32: Just use a #GMutex
*/ */
GMutex * GMutex *
...@@ -556,10 +558,11 @@ g_static_mutex_get_mutex_impl (GStaticMutex* mutex) ...@@ -556,10 +558,11 @@ g_static_mutex_get_mutex_impl (GStaticMutex* mutex)
/** /**
* g_static_mutex_trylock: * g_static_mutex_trylock:
* @mutex: a #GStaticMutex. * @mutex: a #GStaticMutex.
* @Returns: %TRUE, if the #GStaticMutex could be locked.
* *
* Works like g_mutex_trylock(), but for a #GStaticMutex. * Works like g_mutex_trylock(), but for a #GStaticMutex.
* *
* Returns: %TRUE, if the #GStaticMutex could be locked.
*
* Deprecated: 2.32: Use g_mutex_trylock() * Deprecated: 2.32: Use g_mutex_trylock()
*/ */
...@@ -716,7 +719,6 @@ g_static_rec_mutex_lock (GStaticRecMutex* mutex) ...@@ -716,7 +719,6 @@ g_static_rec_mutex_lock (GStaticRecMutex* mutex)
/** /**
* g_static_rec_mutex_trylock: * g_static_rec_mutex_trylock:
* @mutex: a #GStaticRecMutex to lock. * @mutex: a #GStaticRecMutex to lock.
* @Returns: %TRUE, if @mutex could be locked.
* *
* Tries to lock @mutex. If @mutex is already locked by another thread, * Tries to lock @mutex. If @mutex is already locked by another thread,
* it immediately returns %FALSE. Otherwise it locks @mutex and returns * it immediately returns %FALSE. Otherwise it locks @mutex and returns
...@@ -724,6 +726,8 @@ g_static_rec_mutex_lock (GStaticRecMutex* mutex) ...@@ -724,6 +726,8 @@ g_static_rec_mutex_lock (GStaticRecMutex* mutex)
* functions increases the depth of @mutex and immediately returns * functions increases the depth of @mutex and immediately returns
* %TRUE. * %TRUE.
* *
* Returns: %TRUE, if @mutex could be locked.
*
* Deprecated: 2.32: Use g_rec_mutex_trylock() * Deprecated: 2.32: Use g_rec_mutex_trylock()
*/ */
gboolean gboolean
...@@ -789,8 +793,6 @@ g_static_rec_mutex_lock_full (GStaticRecMutex *mutex, ...@@ -789,8 +793,6 @@ g_static_rec_mutex_lock_full (GStaticRecMutex *mutex,
/** /**
* g_static_rec_mutex_unlock_full: * g_static_rec_mutex_unlock_full:
* @mutex: a #GStaticRecMutex to completely unlock. * @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 * Completely unlocks @mutex. If another thread is blocked in a
* g_static_rec_mutex_lock() call for @mutex, it will be woken and can * 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, ...@@ -800,6 +802,9 @@ g_static_rec_mutex_lock_full (GStaticRecMutex *mutex,
* g_static_rec_mutex_lock_full() with the depth returned by this * g_static_rec_mutex_lock_full() with the depth returned by this
* function. * function.
* *
* Returns: number of times @mutex has been locked by the current
* thread.
*
* Deprecated: 2.32: Use g_rec_mutex_unlock() * Deprecated: 2.32: Use g_rec_mutex_unlock()
*/ */
guint guint
...@@ -1024,7 +1029,6 @@ g_static_rw_lock_reader_lock (GStaticRWLock* lock) ...@@ -1024,7 +1029,6 @@ g_static_rw_lock_reader_lock (GStaticRWLock* lock)
/** /**
* g_static_rw_lock_reader_trylock: * g_static_rw_lock_reader_trylock:
* @lock: a #GStaticRWLock to lock for reading. * @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 * Tries to lock @lock for reading. If @lock is already locked for
* writing by another thread or if another thread is already waiting to * writing by another thread or if another thread is already waiting to
...@@ -1032,6 +1036,8 @@ g_static_rw_lock_reader_lock (GStaticRWLock* lock) ...@@ -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 * @lock for reading and returns %TRUE. This lock has to be unlocked by
* g_static_rw_lock_reader_unlock(). * 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 * Deprectated: 2.32: Use g_rw_lock_reader_trylock() instead
*/ */
gboolean gboolean
...@@ -1113,13 +1119,14 @@ g_static_rw_lock_writer_lock (GStaticRWLock* lock) ...@@ -1113,13 +1119,14 @@ g_static_rw_lock_writer_lock (GStaticRWLock* lock)
/** /**
* g_static_rw_lock_writer_trylock: * g_static_rw_lock_writer_trylock:
* @lock: a #GStaticRWLock to lock for writing. * @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 * Tries to lock @lock for writing. If @lock is already locked (for
* either reading or writing) by another thread, it immediately returns * either reading or writing) by another thread, it immediately returns
* %FALSE. Otherwise it locks @lock for writing and returns %TRUE. This * %FALSE. Otherwise it locks @lock for writing and returns %TRUE. This
* lock has to be unlocked by g_static_rw_lock_writer_unlock(). * 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 * Deprectated: 2.32: Use g_rw_lock_writer_trylock() instead
*/ */
gboolean gboolean
......
...@@ -118,7 +118,6 @@ struct _GRealArray ...@@ -118,7 +118,6 @@ struct _GRealArray
* @a: a #GArray. * @a: a #GArray.
* @t: the type of the elements. * @t: the type of the elements.
* @i: the index of the element to return. * @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 * Returns the element of a #GArray at the given index. The return
* value is cast to the given type. * value is cast to the given type.
...@@ -132,6 +131,8 @@ struct _GRealArray ...@@ -132,6 +131,8 @@ struct _GRealArray
* event = &amp;g_array_index (events, EDayViewEvent, 3); * event = &amp;g_array_index (events, EDayViewEvent, 3);
* </programlisting> * </programlisting>
* </example> * </example>
*
* Returns: the element of the #GArray at the index given by @i.
**/ **/
#define g_array_elt_len(array,i) ((array)->elt_size * (i)) #define g_array_elt_len(array,i) ((array)->elt_size * (i))
...@@ -154,9 +155,10 @@ static void g_array_maybe_expand (GRealArray *array, ...@@ -154,9 +155,10 @@ static void g_array_maybe_expand (GRealArray *array,
* @clear_: %TRUE if #GArray elements should be automatically cleared * @clear_: %TRUE if #GArray elements should be automatically cleared
* to 0 when they are allocated. * to 0 when they are allocated.
* @element_size: the size of each element in bytes. * @element_size: the size of each element in bytes.
* @Returns: the new #GArray.
* *
* Creates a new #GArray with a reference count of 1. * Creates a new #GArray with a reference count of 1.
*
* Returns: the new #GArray.
**/ **/
GArray* GArray*
g_array_new (gboolean zero_terminated, g_array_new (gboolean zero_terminated,
...@@ -176,12 +178,13 @@ g_array_new (gboolean zero_terminated, ...@@ -176,12 +178,13 @@ g_array_new (gboolean zero_terminated,
* allocation. * allocation.
* @element_size: size of each element in the array. * @element_size: size of each element in the array.
* @reserved_size: number of elements preallocated. * @reserved_size: number of elements preallocated.
* @Returns: the new #GArray.
* *
* Creates a new #GArray with @reserved_size elements preallocated and * Creates a new #GArray with @reserved_size elements preallocated and
* a reference count of 1. This avoids frequent reallocation, if you * a reference count of 1. This avoids frequent reallocation, if you
* are going to add many elements to the array. Note however that the * are going to add many elements to the array. Note however that the
* size of the array is still 0. * size of the array is still 0.
*
* Returns: the new #GArray.
**/ **/
GArray* g_array_sized_new (gboolean zero_terminated, GArray* g_array_sized_new (gboolean zero_terminated,
gboolean clear, gboolean clear,
...@@ -315,8 +318,6 @@ g_array_get_element_size (GArray *array) ...@@ -315,8 +318,6 @@ g_array_get_element_size (GArray *array)
* g_array_free: * g_array_free:
* @array: a #GArray. * @array: a #GArray.
* @free_segment: if %TRUE the actual element data is freed as well. * @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 * Frees the memory allocated for the #GArray. If @free_segment is
* %TRUE it frees the memory block holding the elements as well and * %TRUE it frees the memory block holding the elements as well and
...@@ -328,6 +329,9 @@ g_array_get_element_size (GArray *array) ...@@ -328,6 +329,9 @@ g_array_get_element_size (GArray *array)
* *
* <note><para>If array elements contain dynamically-allocated memory, * <note><para>If array elements contain dynamically-allocated memory,
* they should be freed separately.</para></note> * 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* gchar*
g_array_free (GArray *farray, g_array_free (GArray *farray,
...@@ -388,15 +392,15 @@ array_free (GRealArray *array, ...@@ -388,15 +392,15 @@ array_free (GRealArray *array,
* @array: a #GArray. * @array: a #GArray.
* @data: a pointer to the elements to append to the end of the array. * @data: a pointer to the elements to append to the end of the array.
* @len: the number of elements to append. * @len: the number of elements to append.
* @Returns: the #GArray.
* *
* Adds @len elements onto the end of the array. * Adds @len elements onto the end of the array.
*
* Returns: the #GArray.
**/ **/
/** /**
* g_array_append_val: * g_array_append_val:
* @a: a #GArray. * @a: a #GArray.
* @v: the value to append to the #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 * Adds the value on to the end of the array. The array will grow in
* size automatically if necessary. * size automatically if necessary.
...@@ -404,6 +408,8 @@ array_free (GRealArray *array, ...@@ -404,6 +408,8 @@ array_free (