Commit 25a7c817 authored by Philip Withnall's avatar Philip Withnall

glib: Add missing (nullable) and (optional) annotations

Add various (nullable) and (optional) annotations which were missing
from a variety of functions. Also port a couple of existing (allow-none)
annotations in the same files to use (nullable) and (optional) as
appropriate instead.

Secondly, add various (not nullable) annotations as needed by the new
default in gobject-introspection of marking gpointers as (nullable). See
https://bugzilla.gnome.org/show_bug.cgi?id=729660.

This includes adding some stub documentation comments for the
assertion macro error functions, which weren’t previously documented.
The new comments are purely to allow for annotations, and hence are
marked as (skip) to prevent the symbols appearing in the GIR file.

https://bugzilla.gnome.org/show_bug.cgi?id=719966
parent 90808a02
......@@ -55,7 +55,8 @@ g_converter_default_init (GConverterInterface *iface)
* @inbuf: (array length=inbuf_size) (element-type guint8): the buffer
* containing the data to convert.
* @inbuf_size: the number of bytes in @inbuf
* @outbuf: a buffer to write converted data in.
* @outbuf: (element-type guint8) (array length=outbuf_size): a buffer to write
* converted data in.
* @outbuf_size: the number of bytes in @outbuf, must be at least one
* @flags: a #GConverterFlags controlling the conversion details
* @bytes_read: (out): will be set to the number of bytes read from @inbuf on success
......
......@@ -393,7 +393,7 @@ g_credentials_get_native (GCredentials *credentials,
* g_credentials_set_native:
* @credentials: A #GCredentials.
* @native_type: The type of native credentials to set.
* @native: A pointer to native credentials.
* @native: (not nullable): A pointer to native credentials.
*
* Copies the native credentials of type @native_type from @native
* into @credentials.
......
......@@ -487,7 +487,7 @@ typedef GDBusInterfaceInfo ** (*GDBusSubtreeIntrospectFunc) (GDBusConnection
* @object_path: The object path that was registered with g_dbus_connection_register_subtree().
* @interface_name: The D-Bus interface name that the method call or property access is for.
* @node: A node that is a child of @object_path (relative to @object_path) or %NULL for the root of the subtree.
* @out_user_data: Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
* @out_user_data: (nullable) (not optional): Return location for user data to pass to functions in the returned #GDBusInterfaceVTable (never %NULL).
* @user_data: The @user_data #gpointer passed to g_dbus_connection_register_subtree().
*
* The type of the @dispatch function in #GDBusSubtreeVTable.
......
......@@ -711,9 +711,10 @@ g_file_info_remove_attribute (GFileInfo *info,
* g_file_info_get_attribute_data:
* @info: a #GFileInfo
* @attribute: a file attribute key
* @type: (out) (allow-none): return location for the attribute type, or %NULL
* @value_pp: (out) (allow-none): return location for the attribute value, or %NULL
* @status: (out) (allow-none): return location for the attribute status, or %NULL
* @type: (out) (optional): return location for the attribute type, or %NULL
* @value_pp: (out) (optional) (not nullable): return location for the
* attribute value, or %NULL; the attribute value will not be %NULL
* @status: (out) (optional): return location for the attribute status, or %NULL
*
* Gets the attribute type, value and status for an attribute key.
*
......@@ -1108,7 +1109,7 @@ _g_file_info_set_attribute_by_id (GFileInfo *info,
* @info: a #GFileInfo.
* @attribute: a file attribute key.
* @type: a #GFileAttributeType
* @value_p: pointer to the value
* @value_p: (not nullable): pointer to the value
*
* Sets the @attribute to contain the given value, if possible. To unset the
* attribute, use %G_ATTRIBUTE_TYPE_INVALID for @type.
......
......@@ -83,7 +83,7 @@ g_icon_default_init (GIconInterface *iface)
/**
* g_icon_hash:
* @icon: #gconstpointer to an icon object.
* @icon: (not nullable): #gconstpointer to an icon object.
*
* Gets a hash for an icon.
*
......
......@@ -422,7 +422,8 @@ g_memory_output_stream_new_resizable (void)
* Note that the returned pointer may become invalid on the next
* write or truncate operation on the stream.
*
* Returns: (transfer none): pointer to the stream's data
* Returns: (transfer none): pointer to the stream's data, or %NULL if the data
* has been stolen
**/
gpointer
g_memory_output_stream_get_data (GMemoryOutputStream *ostream)
......@@ -492,7 +493,8 @@ g_memory_output_stream_get_data_size (GMemoryOutputStream *ostream)
*
* @ostream must be closed before calling this function.
*
* Returns: (transfer full): the stream's data
* Returns: (transfer full): the stream's data, or %NULL if it has previously
* been stolen
*
* Since: 2.26
**/
......
......@@ -192,7 +192,7 @@ g_socket_address_to_native (GSocketAddress *address,
/**
* g_socket_address_new_from_native:
* @native: a pointer to a struct sockaddr
* @native: (not nullable): a pointer to a struct sockaddr
* @len: the size of the memory location pointed to by @native
*
* Creates a #GSocketAddress subclass corresponding to the native
......
......@@ -118,7 +118,7 @@ g_socket_control_message_get_msg_type (GSocketControlMessage *message)
/**
* g_socket_control_message_serialize:
* @message: a #GSocketControlMessage
* @data: A buffer to write data to
* @data: (not nullable): A buffer to write data to
*
* Converts the data in the message to bytes placed in the
* message.
......
......@@ -385,7 +385,7 @@ array_free (GRealArray *array,
/**
* g_array_append_vals:
* @array: a #GArray
* @data: a pointer to the elements to append to the end of the array
* @data: (not nullable): a pointer to the elements to append to the end of the array
* @len: the number of elements to append
*
* Adds @len elements onto the end of the array.
......@@ -430,7 +430,7 @@ g_array_append_vals (GArray *farray,
/**
* g_array_prepend_vals:
* @array: a #GArray
* @data: a pointer to the elements to prepend to the start of the array
* @data: (not nullable): a pointer to the elements to prepend to the start of the array
* @len: the number of elements to prepend
*
* Adds @len elements onto the start of the array.
......@@ -486,7 +486,7 @@ g_array_prepend_vals (GArray *farray,
* g_array_insert_vals:
* @array: a #GArray
* @index_: the index to place the elements at
* @data: a pointer to the elements to insert
* @data: (not nullable): a pointer to the elements to insert
* @len: the number of elements to insert
*
* Inserts @len elements into a #GArray at the given index.
......
......@@ -301,7 +301,7 @@ guint
/**
* g_atomic_pointer_get:
* @atomic: a pointer to a #gpointer-sized value
* @atomic: (not nullable): a pointer to a #gpointer-sized value
*
* Gets the current value of @atomic.
*
......@@ -320,7 +320,7 @@ gpointer
/**
* g_atomic_pointer_set:
* @atomic: a pointer to a #gpointer-sized value
* @atomic: (not nullable): a pointer to a #gpointer-sized value
* @newval: a new value to store
*
* Sets the value of @atomic to @newval.
......@@ -339,7 +339,7 @@ void
/**
* g_atomic_pointer_compare_and_exchange:
* @atomic: a pointer to a #gpointer-sized value
* @atomic: (not nullable): a pointer to a #gpointer-sized value
* @oldval: the value to compare with
* @newval: the value to conditionally replace with
*
......@@ -368,7 +368,7 @@ gboolean
/**
* g_atomic_pointer_add:
* @atomic: a pointer to a #gpointer-sized value
* @atomic: (not nullable): a pointer to a #gpointer-sized value
* @val: the value to add
*
* Atomically adds @val to the value of @atomic.
......@@ -391,7 +391,7 @@ gssize
/**
* g_atomic_pointer_and:
* @atomic: a pointer to a #gpointer-sized value
* @atomic: (not nullable): a pointer to a #gpointer-sized value
* @val: the value to 'and'
*
* Performs an atomic bitwise 'and' of the value of @atomic and @val,
......@@ -415,7 +415,7 @@ gsize
/**
* g_atomic_pointer_or:
* @atomic: a pointer to a #gpointer-sized value
* @atomic: (not nullable): a pointer to a #gpointer-sized value
* @val: the value to 'or'
*
* Performs an atomic bitwise 'or' of the value of @atomic and @val,
......@@ -439,7 +439,7 @@ gsize
/**
* g_atomic_pointer_xor:
* @atomic: a pointer to a #gpointer-sized value
* @atomic: (not nullable): a pointer to a #gpointer-sized value
* @val: the value to 'xor'
*
* Performs an atomic bitwise 'xor' of the value of @atomic and @val,
......
......@@ -385,7 +385,7 @@ g_futex_int_address (const volatile void *address)
/**
* g_pointer_bit_lock:
* @address: a pointer to a #gpointer-sized value
* @address: (not nullable): a pointer to a #gpointer-sized value
* @lock_bit: a bit value between 0 and 31
*
* This is equivalent to g_bit_lock, but working on pointers (or other
......@@ -454,7 +454,7 @@ void
/**
* g_pointer_bit_trylock:
* @address: a pointer to a #gpointer-sized value
* @address: (not nullable): a pointer to a #gpointer-sized value
* @lock_bit: a bit value between 0 and 31
*
* This is equivalent to g_bit_trylock, but working on pointers (or
......@@ -501,7 +501,7 @@ gboolean
/**
* g_pointer_bit_unlock:
* @address: a pointer to a #gpointer-sized value
* @address: (not nullable): a pointer to a #gpointer-sized value
* @lock_bit: a bit value between 0 and 31
*
* This is equivalent to g_bit_unlock, but working on pointers (or other
......
......@@ -436,8 +436,9 @@ try_steal_and_unref (GBytes *bytes,
* g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the
* data is copied.
*
* Returns: (transfer full) (array length=size) (element-type guint8):
* a pointer to the same byte data, which should be freed with g_free()
* Returns: (transfer full) (array length=size) (element-type guint8)
* (not nullable): a pointer to the same byte data, which should be
* freed with g_free()
*
* Since: 2.32
*/
......
......@@ -872,7 +872,7 @@ strdup_len (const gchar *string,
* nul-terminated (Note that some encodings may allow nul
* bytes to occur inside strings. In that case, using -1
* for the @len parameter is unsafe)
* @bytes_read: location to store the number of bytes in the
* @bytes_read: (out) (optional): location to store the number of bytes in the
* input string that were successfully converted, or %NULL.
* Even if the conversion was successful, this may be
* less than @len if there were partial characters
......@@ -880,8 +880,8 @@ strdup_len (const gchar *string,
* #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
* stored will the byte offset after the last valid
* input sequence.
* @bytes_written: the number of bytes stored in the output buffer (not
* including the terminating nul).
* @bytes_written: (out) (optional): the number of bytes stored in the output
* buffer (not including the terminating nul).
* @error: location to store the error occurring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
*
......@@ -915,7 +915,7 @@ g_locale_to_utf8 (const gchar *opsysstring,
* nul-terminated (Note that some encodings may allow nul
* bytes to occur inside strings. In that case, using -1
* for the @len parameter is unsafe)
* @bytes_read: location to store the number of bytes in the
* @bytes_read: (out) (optional): location to store the number of bytes in the
* input string that were successfully converted, or %NULL.
* Even if the conversion was successful, this may be
* less than @len if there were partial characters
......@@ -923,8 +923,8 @@ g_locale_to_utf8 (const gchar *opsysstring,
* #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
* stored will the byte offset after the last valid
* input sequence.
* @bytes_written: the number of bytes stored in the output buffer (not
* including the terminating nul).
* @bytes_written: (out) (optional): the number of bytes stored in the output
* buffer (not including the terminating nul).
* @error: location to store the error occurring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
*
......@@ -1119,7 +1119,7 @@ get_filename_charset (const gchar **filename_charset)
* nul-terminated (Note that some encodings may allow nul
* bytes to occur inside strings. In that case, using -1
* for the @len parameter is unsafe)
* @bytes_read: location to store the number of bytes in the
* @bytes_read: (out) (optional): location to store the number of bytes in the
* input string that were successfully converted, or %NULL.
* Even if the conversion was successful, this may be
* less than @len if there were partial characters
......@@ -1127,8 +1127,8 @@ get_filename_charset (const gchar **filename_charset)
* #G_CONVERT_ERROR_ILLEGAL_SEQUENCE occurs, the value
* stored will the byte offset after the last valid
* input sequence.
* @bytes_written: the number of bytes stored in the output buffer (not
* including the terminating nul).
* @bytes_written: (out) (optional): the number of bytes stored in the output
* buffer (not including the terminating nul).
* @error: location to store the error occurring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
*
......@@ -1191,7 +1191,7 @@ g_filename_to_utf8 (const gchar *opsysstring,
* @utf8string: a UTF-8 encoded string.
* @len: the length of the string, or -1 if the string is
* nul-terminated.
* @bytes_read: (out) (allow-none): location to store the number of bytes in
* @bytes_read: (out) (optional): location to store the number of bytes in
* the input string that were successfully converted, or %NULL.
* Even if the conversion was successful, this may be
* less than @len if there were partial characters
......@@ -1530,7 +1530,8 @@ hostname_validate (const char *hostname)
/**
* g_filename_from_uri:
* @uri: a uri describing a filename (escaped, encoded in ASCII).
* @hostname: (out) (allow-none): Location to store hostname for the URI, or %NULL.
* @hostname: (out) (optional) (nullable): Location to store hostname for the
* URI.
* If there is no hostname in the URI, %NULL will be
* stored in this location.
* @error: location to store the error occurring, or %NULL to ignore
......
......@@ -318,7 +318,7 @@ g_dataset_destroy_internal (GDataset *dataset)
/**
* g_dataset_destroy:
* @dataset_location: the location identifying the dataset.
* @dataset_location: (not nullable): the location identifying the dataset.
*
* Destroys the dataset, freeing all memory allocated, and calling any
* destroy functions set for data elements.
......@@ -487,7 +487,7 @@ g_data_set_internal (GData **datalist,
/**
* g_dataset_id_set_data_full:
* @dataset_location: the location identifying the dataset.
* @dataset_location: (not nullable): the location identifying the dataset.
* @key_id: the #GQuark id to identify the data element.
* @data: the data element.
* @destroy_func: the function to call when the data element is
......@@ -672,7 +672,7 @@ g_datalist_id_set_data_full (GData **datalist,
/**
* g_dataset_id_remove_no_notify:
* @dataset_location: the location identifying the dataset.
* @dataset_location: (not nullable): the location identifying the dataset.
* @key_id: the #GQuark ID identifying the data element.
*
* Removes an element, without calling its destroy notification
......@@ -742,7 +742,7 @@ g_datalist_id_remove_no_notify (GData **datalist,
/**
* g_dataset_id_get_data:
* @dataset_location: the location identifying the dataset.
* @dataset_location: (not nullable): the location identifying the dataset.
* @key_id: the #GQuark id to identify the data element.
*
* Gets the data element corresponding to a #GQuark.
......@@ -1054,7 +1054,7 @@ g_datalist_get_data (GData **datalist,
/**
* g_dataset_foreach:
* @dataset_location: the location identifying the dataset.
* @dataset_location: (not nullable): the location identifying the dataset.
* @func: the function to call for each data element.
* @user_data: user data to pass to the function.
*
......
......@@ -1938,7 +1938,7 @@ g_date_compare (const GDate *lhs,
/**
* g_date_to_struct_tm:
* @date: a #GDate to set the struct tm from
* @tm: struct tm to fill
* @tm: (not nullable): struct tm to fill
*
* Fills in the date-related bits of a struct tm using the @date value.
* Initializes the non-date parts with something sane but meaningless.
......
......@@ -1363,8 +1363,8 @@ g_date_time_add_full (GDateTime *datetime,
/* Compare, difference, hash, equal {{{1 */
/**
* g_date_time_compare:
* @dt1: first #GDateTime to compare
* @dt2: second #GDateTime to compare
* @dt1: (not nullable): first #GDateTime to compare
* @dt2: (not nullable): second #GDateTime to compare
*
* A comparison function for #GDateTimes that is suitable
* as a #GCompareFunc. Both #GDateTimes must be non-%NULL.
......@@ -1419,7 +1419,7 @@ g_date_time_difference (GDateTime *end,
/**
* g_date_time_hash:
* @datetime: a #GDateTime
* @datetime: (not nullable): a #GDateTime
*
* Hashes @datetime into a #guint, suitable for use within #GHashTable.
*
......@@ -1435,8 +1435,8 @@ g_date_time_hash (gconstpointer datetime)
/**
* g_date_time_equal:
* @dt1: a #GDateTime
* @dt2: a #GDateTime
* @dt1: (not nullable): a #GDateTime
* @dt2: (not nullable): a #GDateTime
*
* Checks to see if @dt1 and @dt2 are equal.
*
......
......@@ -525,7 +525,7 @@ g_error_copy (const GError *error)
/**
* g_error_matches:
* @error: (allow-none): a #GError or %NULL
* @error: (nullable): a #GError
* @domain: an error domain
* @code: an error code
*
......@@ -558,7 +558,7 @@ g_error_matches (const GError *error,
/**
* g_set_error:
* @err: (allow-none): a return location for a #GError, or %NULL
* @err: (out callee-allocates) (optional): a return location for a #GError
* @domain: error domain
* @code: error code
* @format: printf()-style format
......@@ -596,7 +596,7 @@ g_set_error (GError **err,
/**
* g_set_error_literal:
* @err: (allow-none): a return location for a #GError, or %NULL
* @err: (out callee-allocates) (optional): a return location for a #GError
* @domain: error domain
* @code: error code
* @message: error message
......@@ -697,7 +697,7 @@ g_error_add_prefix (gchar **string,
/**
* g_prefix_error:
* @err: (allow-none): a return location for a #GError, or %NULL
* @err: (inout) (optional) (nullable): a return location for a #GError
* @format: printf()-style format string
* @...: arguments to @format
*
......
......@@ -767,8 +767,8 @@ g_hash_table_iter_init (GHashTableIter *iter,
/**
* g_hash_table_iter_next:
* @iter: an initialized #GHashTableIter
* @key: (allow-none): a location to store the key, or %NULL
* @value: (allow-none): a location to store the value, or %NULL
* @key: (out) (optional): a location to store the key
* @value: (out) (nullable) (optional): a location to store the value
*
* Advances @iter and retrieves the key and/or value that are now
* pointed to as a result of this advancement. If %FALSE is returned,
......@@ -1155,8 +1155,9 @@ g_hash_table_lookup (GHashTable *hash_table,
* g_hash_table_lookup_extended:
* @hash_table: a #GHashTable
* @lookup_key: the key to look up
* @orig_key: (allow-none): return location for the original key, or %NULL
* @value: (allow-none): return location for the value associated with the key, or %NULL
* @orig_key: (allow-none): return location for the original key
* @value: (out) (optional) (nullable): return location for the value associated
* with the key
*
* Looks up a key in the #GHashTable, returning the original key and the
* associated value and a #gboolean which is %TRUE if the key was found. This
......@@ -1821,8 +1822,8 @@ g_hash_table_get_values (GHashTable *hash_table)
/**
* g_str_equal:
* @v1: a key
* @v2: a key to compare with @v1
* @v1: (not nullable): a key
* @v2: (not nullable): a key to compare with @v1
*
* Compares two strings for byte-by-byte equality and returns %TRUE
* if they are equal. It can be passed to g_hash_table_new() as the
......@@ -1847,7 +1848,7 @@ g_str_equal (gconstpointer v1,
/**
* g_str_hash:
* @v: a string key
* @v: (not nullable): a string key
*
* Converts a string to a hash value.
*
......@@ -1922,8 +1923,8 @@ g_direct_equal (gconstpointer v1,
/**
* g_int_equal:
* @v1: a pointer to a #gint key
* @v2: a pointer to a #gint key to compare with @v1
* @v1: (not nullable): a pointer to a #gint key
* @v2: (not nullable): a pointer to a #gint key to compare with @v1
*
* Compares the two #gint values being pointed to and returns
* %TRUE if they are equal.
......@@ -1946,7 +1947,7 @@ g_int_equal (gconstpointer v1,
/**
* g_int_hash:
* @v: a pointer to a #gint key
* @v: (not nullable): a pointer to a #gint key
*
* Converts a pointer to a #gint to a hash value.
* It can be passed to g_hash_table_new() as the @hash_func parameter,
......@@ -1966,8 +1967,8 @@ g_int_hash (gconstpointer v)
/**
* g_int64_equal:
* @v1: a pointer to a #gint64 key
* @v2: a pointer to a #gint64 key to compare with @v1
* @v1: (not nullable): a pointer to a #gint64 key
* @v2: (not nullable): a pointer to a #gint64 key to compare with @v1
*
* Compares the two #gint64 values being pointed to and returns
* %TRUE if they are equal.
......@@ -1988,7 +1989,7 @@ g_int64_equal (gconstpointer v1,
/**
* g_int64_hash:
* @v: a pointer to a #gint64 key
* @v: (not nullable): a pointer to a #gint64 key
*
* Converts a pointer to a #gint64 to a hash value.
*
......@@ -2008,8 +2009,8 @@ g_int64_hash (gconstpointer v)
/**
* g_double_equal:
* @v1: a pointer to a #gdouble key
* @v2: a pointer to a #gdouble key to compare with @v1
* @v1: (not nullable): a pointer to a #gdouble key
* @v2: (not nullable): a pointer to a #gdouble key to compare with @v1
*
* Compares the two #gdouble values being pointed to and returns
* %TRUE if they are equal.
......@@ -2030,7 +2031,7 @@ g_double_equal (gconstpointer v1,
/**
* g_double_hash:
* @v: a pointer to a #gdouble key
* @v: (not nullable): a pointer to a #gdouble key
*
* Converts a pointer to a #gdouble to a hash value.
* It can be passed to g_hash_table_new() as the @hash_func parameter,
......
......@@ -453,7 +453,7 @@ g_hook_prepend (GHookList *hook_list,
/**
* g_hook_insert_before:
* @hook_list: a #GHookList
* @sibling: the #GHook to insert the new #GHook before
* @sibling: (nullable): the #GHook to insert the new #GHook before
* @hook: the #GHook to insert
*
* Inserts a #GHook into a #GHookList, before a given #GHook.
......@@ -930,7 +930,7 @@ g_hook_find_func (GHookList *hook_list,
* @hook_list: a #GHookList
* @need_valids: %TRUE if #GHook elements which have been destroyed
* should be skipped
* @func: the function to find
* @func: (not nullable): the function to find
* @data: the data to find
*
* Finds a #GHook in a #GHookList with the given function and data.
......
......@@ -2361,7 +2361,7 @@ g_source_remove_by_funcs_user_data (GSourceFuncs *funcs,
*
* As the name suggests, this function is not available on Windows.
*
* Returns: an opaque tag
* Returns: (not nullable): an opaque tag
*
* Since: 2.36
**/
......@@ -2401,7 +2401,7 @@ g_source_add_unix_fd (GSource *source,
/**
* g_source_modify_unix_fd:
* @source: a #GSource
* @tag: the tag from g_source_add_unix_fd()
* @tag: (not nullable): the tag from g_source_add_unix_fd()
* @new_events: the new event mask to watch
*
* Updates the event mask to watch for the fd identified by @tag.
......@@ -2441,7 +2441,7 @@ g_source_modify_unix_fd (GSource *source,
/**
* g_source_remove_unix_fd:
* @source: a #GSource
* @tag: the tag from g_source_add_unix_fd()
* @tag: (not nullable): the tag from g_source_add_unix_fd()
*
* Reverses the effect of a previous call to g_source_add_unix_fd().
*
......@@ -2488,7 +2488,7 @@ g_source_remove_unix_fd (GSource *source,
/**
* g_source_query_unix_fd:
* @source: a #GSource
* @tag: the tag from g_source_add_unix_fd()
* @tag: (not nullable): the tag from g_source_add_unix_fd()
*
* Queries the events reported for the fd corresponding to @tag on
* @source during the last poll.
......
......@@ -192,7 +192,8 @@ g_free (gpointer mem)
/**
* g_clear_pointer: (skip)
* @pp: a pointer to a variable, struct member etc. holding a pointer
* @pp: (not nullable): a pointer to a variable, struct member etc. holding a
* pointer
* @destroy: a function to which a gpointer can be passed, to destroy *@pp
*
* Clears a reference to a variable.
......
......@@ -129,7 +129,7 @@ gpointer g_try_realloc_n (gpointer mem,
/**
* g_steal_pointer:
* @pp: a pointer to a pointer
* @pp: (not nullable): a pointer to a pointer
*
* Sets @pp to %NULL, returning the value that was there before.
*
......
......@@ -942,7 +942,8 @@ static GSList *expected_messages = NULL;
/**
* g_logv:
* @log_domain: the log domain
* @log_domain: (nullable): the log domain, or %NULL for the default ""
* application domain
* @log_level: the log level
* @format: the message format. See the printf() documentation
* @args: the parameters to insert into the format string
......@@ -1089,7 +1090,8 @@ g_logv (const gchar *log_domain,
/**
* g_log:
* @log_domain: the log domain, usually #G_LOG_DOMAIN
* @log_domain: (nullable): the log domain, usually #G_LOG_DOMAIN, or %NULL
* for the default
* @log_level: the log level, either from #GLogLevelFlags
* or a user-defined level
* @format: the message format. See the printf() documentation
......@@ -1117,6 +1119,12 @@ g_log (const gchar *log_domain,
va_end (args);
}
/**
* g_return_if_fail_warning: (skip)
* @log_domain: (nullable):
* @pretty_function:
* @expression: (nullable):
*/
void
g_return_if_fail_warning (const char *log_domain,
const char *pretty_function,
......@@ -1129,6 +1137,14 @@ g_return_if_fail_warning (const char *log_domain,
expression);
}
/**
* g_warn_message: (skip)
* @domain: (nullable):
* @file:
* @line:
* @func:
* @warnexpr: (nullable):
*/
void
g_warn_message (const char *domain,
const char *file,
......@@ -1379,10 +1395,11 @@ escape_string (GString *string)
/**
* g_log_default_handler:
* @log_domain: the log domain of the message
* @log_domain: (nullable): the log domain of the message, or %NULL for the
* default "" application domain
* @log_level: the level of the message
* @message: the message
* @unused_data: data passed from g_log() which is unused
* @message: (nullable): the message
* @unused_data: (nullable): data passed from g_log() which is unused
*
* The default log handler set up by GLib; g_log_set_default_handler()
* allows to install an alternate default log handler.
......
......@@ -62,13 +62,13 @@ typedef void (*GNodeForeachFunc) (GNode *node,
/**
* GCopyFunc:
* @src: A pointer to the data which should be copied
* @src: (not nullable): A pointer to the data which should be copied
* @data: Additional data
*
* A function of this signature is used to copy the node data
* when doing a deep-copy of a tree.
*
* Returns: A pointer to the copy
* Returns: (not nullable): A pointer to the copy
*
* Since: 2.4
*/
......
......@@ -58,7 +58,7 @@ g_printf (gchar const *format,
/**
* g_fprintf:
* @file: the stream to write to.
* @file: (not nullable): the stream to write to.
* @format: a standard printf() format string, but notice
* [string precision pitfalls][string-precision]
* @...: the arguments to insert in the output.
......@@ -191,7 +191,7 @@ g_vprintf (gchar const *format,
/**
* g_vfprintf:
* @file: the stream to write to.
* @file: (not nullable): the stream to write to.
* @format: a standard printf() format string, but notice
* [string precision pitfalls][string-precision]
* @args: the list of arguments to insert in the output.
......
......@@ -282,7 +282,7 @@ msort_r (void *b, size_t n, size_t s, GCompareDataFunc cmp, void *arg)
/**
* g_qsort_with_data:
* @pbase: start of array to sort
* @pbase: (not nullable): start of array to sort
* @total_elems: elements in the array
* @size: size of each element
* @compare_func: function to compare elements
......
......@@ -619,10 +619,10 @@ tokenize_command_line (const gchar *command_line,
/**
* g_shell_parse_argv:
* @command_line: command line to parse
* @argcp: (out) (optional): return location for number of args, or %NULL
* @argcp: (out) (optional): return location for number of args
* @argvp: (out) (optional) (array length=argcp zero-terminated=1): return
* location for array of args, or %NULL
* @error: (optional): return location for error, or %NULL
* location for array of args
* @error: (optional): return location for error
*
* Parses a command line into an argument vector, in much the same way
* the shell would, but without many of the expansions the shell would
......
......@@ -873,7 +873,11 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
* mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE]
* environment variable.
*
* Returns: a pointer to the allocated block, cast to a pointer to @type
* This can never return %NULL as the minimum allocation size from
* `sizeof (@type)` is 1 byte.
*
* Returns: (not nullable): a pointer to the allocated block, cast to a pointer
* to @type
*
* Since: 2.10
*/
......@@ -892,13 +896,19 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
* be changed with the [`G_SLICE=always-malloc`][G_SLICE]
* environment variable.
*
* This can never return %NULL as the minimum allocation size from
* `sizeof (@type)` is 1 byte.
*
* Returns: (not nullable): a pointer to the allocated block, cast to a pointer
* to @type
*
* Since: 2.10
*/
/**
* g_slice_dup:
* @type: the type to duplicate, typically a structure name
* @mem: the memory to copy into the allocated block
* @mem: (not nullable): the memory to copy into the allocated block
*
* A convenience macro to duplicate a block of memory using
* the slice allocator.
......@@ -910,7 +920,10 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
* be changed with the [`G_SLICE=always-malloc`][G_SLICE]
* environment variable.
*
* Returns: a pointer to the allocated block, cast to a pointer to @type
* This can never return %NULL.
*
* Returns: (not nullable): a pointer to the allocated block, cast to a pointer
* to @type
*
* Since: 2.14
*/
......@@ -929,6 +942,8 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
* [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
* [`G_SLICE`][G_SLICE] for related debugging options.
*
* If @mem is %NULL, this macro does nothing.
*
* Since: 2.10
*/
......@@ -947,6 +962,8 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
* [`G_DEBUG=gc-friendly`][G_DEBUG] environment variable, also see
* [`G_SLICE`][G_SLICE] for related debugging options.
*
* If @mem_chain is %NULL, this function does nothing.
<