diff options
author | Rico Tzschichholz <ricotz@ubuntu.com> | 2020-12-16 20:31:10 +0100 |
---|---|---|
committer | Rico Tzschichholz <ricotz@ubuntu.com> | 2020-12-16 20:31:10 +0100 |
commit | d46e38b9e208e10c6db1ac07fdd75bba7baeaaf1 (patch) | |
tree | 5b1234a60f3cbd492d0adf8a9fdee425ef6ecd3a /gir | |
parent | 132d09e4809ec022ad14e734fc5228b769cc4b14 (diff) | |
download | gobject-introspection-d46e38b9e208e10c6db1ac07fdd75bba7baeaaf1.tar.gz |
gir: Update annotations from glib git master
Diffstat (limited to 'gir')
-rw-r--r-- | gir/gio-2.0.c | 97 | ||||
-rw-r--r-- | gir/glib-2.0.c | 147 | ||||
-rw-r--r-- | gir/gobject-2.0.c | 168 |
3 files changed, 282 insertions, 130 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index b925400a..f3f865f2 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -737,7 +737,7 @@ * * If you are constructing a #GDBusConnection and pass * %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_SERVER in the - * #GDBusConnection:flags property then you MUST also set this + * #GDBusConnection:flags property then you **must** also set this * property to a valid guid. * * If you are constructing a #GDBusConnection and pass @@ -5688,12 +5688,12 @@ * GQuark * foo_bar_error_quark (void) * { - * static volatile gsize quark_volatile = 0; + * static gsize quark = 0; * g_dbus_error_register_error_domain ("foo-bar-error-quark", - * &quark_volatile, + * &quark, * foo_bar_error_entries, * G_N_ELEMENTS (foo_bar_error_entries)); - * return (GQuark) quark_volatile; + * return (GQuark) quark; * } * ]| * With this setup, a D-Bus peer can transparently pass e.g. %FOO_BAR_ERROR_ANOTHER_ERROR and @@ -14157,10 +14157,10 @@ * logged) to use this method if there is no #GCredentials support for * the OS or if @native_type isn't supported by the OS. * - * Returns: The pointer to native credentials or %NULL if the - * operation there is no #GCredentials support for the OS or if - * @native_type isn't supported by the OS. Do not free the returned - * data, it is owned by @credentials. + * Returns: (transfer none) (nullable): The pointer to native credentials or + * %NULL if there is no #GCredentials support for the OS or if @native_type + * isn't supported by the OS. Do not free the returned data, it is owned + * by @credentials. * Since: 2.26 */ @@ -14178,7 +14178,7 @@ * about the UNIX process ID (for example this is the case for * %G_CREDENTIALS_TYPE_APPLE_XUCRED). * - * Returns: The UNIX process ID, or -1 if @error is set. + * Returns: The UNIX process ID, or `-1` if @error is set. * Since: 2.36 */ @@ -14195,7 +14195,7 @@ * OS or if the native credentials type does not contain information * about the UNIX user. * - * Returns: The UNIX user identifier or -1 if @error is set. + * Returns: The UNIX user identifier or `-1` if @error is set. * Since: 2.26 */ @@ -14223,7 +14223,7 @@ * Creates a new #GCredentials object with credentials matching the * the current process. * - * Returns: A #GCredentials. Free with g_object_unref(). + * Returns: (transfer full): A #GCredentials. Free with g_object_unref(). * Since: 2.26 */ @@ -14272,7 +14272,7 @@ * that can be used in logging and debug messages. The format of the * returned string may change in future GLib release. * - * Returns: A string that should be freed with g_free(). + * Returns: (transfer full): A string that should be freed with g_free(). * Since: 2.26 */ @@ -15178,11 +15178,14 @@ /** * g_dbus_address_get_stream_finish: * @res: A #GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_address_get_stream(). - * @out_guid: (optional) (out): %NULL or return location to store the GUID extracted from @address, if any. + * @out_guid: (optional) (out) (nullable): %NULL or return location to store the GUID extracted from @address, if any. * @error: Return location for error or %NULL. * * Finishes an operation started with g_dbus_address_get_stream(). * + * A server is not required to set a GUID, so @out_guid may be set to %NULL + * even on success. + * * Returns: (transfer full): A #GIOStream or %NULL if @error is set. * Since: 2.26 */ @@ -15191,7 +15194,7 @@ /** * g_dbus_address_get_stream_sync: * @address: A valid D-Bus address. - * @out_guid: (optional) (out): %NULL or return location to store the GUID extracted from @address, if any. + * @out_guid: (optional) (out) (nullable): %NULL or return location to store the GUID extracted from @address, if any. * @cancellable: (nullable): A #GCancellable or %NULL. * @error: Return location for error or %NULL. * @@ -15200,6 +15203,9 @@ * of the D-Bus authentication conversation. @address must be in the * [D-Bus address format](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses). * + * A server is not required to set a GUID, so @out_guid may be set to %NULL + * even on success. + * * This is a synchronous failable function. See * g_dbus_address_get_stream() for the asynchronous version. * @@ -15426,8 +15432,8 @@ * * Finishes an operation started with g_dbus_connection_call(). * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). + * Returns: (transfer full): %NULL if @error is set. Otherwise a non-floating + * #GVariant tuple with return values. Free with g_variant_unref(). * Since: 2.26 */ @@ -15486,8 +15492,8 @@ * g_dbus_connection_call() for the asynchronous version of * this method. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). + * Returns: (transfer full): %NULL if @error is set. Otherwise a non-floating + * #GVariant tuple with return values. Free with g_variant_unref(). * Since: 2.26 */ @@ -15554,8 +15560,8 @@ * access file descriptors if they are referenced in this way by a * value of type %G_VARIANT_TYPE_HANDLE in the body of the message. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). + * Returns: (transfer full): %NULL if @error is set. Otherwise a non-floating + * #GVariant tuple with return values. Free with g_variant_unref(). * Since: 2.30 */ @@ -15585,8 +15591,8 @@ * * This method is only available on UNIX. * - * Returns: %NULL if @error is set. Otherwise a #GVariant tuple with - * return values. Free with g_variant_unref(). + * Returns: (transfer full): %NULL if @error is set. Otherwise a non-floating + * #GVariant tuple with return values. Free with g_variant_unref(). * Since: 2.30 */ @@ -15842,7 +15848,7 @@ * The GUID of the peer performing the role of server when * authenticating. See #GDBusConnection:guid for more details. * - * Returns: The GUID. Do not free this string, it is owned by + * Returns: (not nullable): The GUID. Do not free this string, it is owned by * @connection. * Since: 2.26 */ @@ -15894,7 +15900,7 @@ * stream from a worker thread, so it is not safe to interact with * the stream directly. * - * Returns: (transfer none): the stream used for IO + * Returns: (transfer none) (not nullable): the stream used for IO * Since: 2.26 */ @@ -15968,7 +15974,7 @@ * * Finishes an operation started with g_dbus_connection_new(). * - * Returns: a #GDBusConnection or %NULL if @error is set. Free + * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. Free * with g_object_unref(). * Since: 2.26 */ @@ -16017,8 +16023,8 @@ * * Finishes an operation started with g_dbus_connection_new_for_address(). * - * Returns: a #GDBusConnection or %NULL if @error is set. Free with - * g_object_unref(). + * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. + * Free with g_object_unref(). * Since: 2.26 */ @@ -16048,8 +16054,8 @@ * If @observer is not %NULL it may be used to control the * authentication process. * - * Returns: a #GDBusConnection or %NULL if @error is set. Free with - * g_object_unref(). + * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. + * Free with g_object_unref(). * Since: 2.26 */ @@ -16079,7 +16085,8 @@ * This is a synchronous failable constructor. See * g_dbus_connection_new() for the asynchronous version. * - * Returns: a #GDBusConnection or %NULL if @error is set. Free with g_object_unref(). + * Returns: (transfer full): a #GDBusConnection or %NULL if @error is set. + * Free with g_object_unref(). * Since: 2.26 */ @@ -16152,7 +16159,7 @@ * Version of g_dbus_connection_register_object() using closures instead of a * #GDBusInterfaceVTable for easier binding in other languages. * - * Returns: 0 if @error is set, otherwise a registration id (never 0) + * Returns: 0 if @error is set, otherwise a registration ID (never 0) * that can be used with g_dbus_connection_unregister_object() . * Since: 2.46 */ @@ -16204,8 +16211,8 @@ * See this [server][gdbus-subtree-server] for an example of how to use * this method. * - * Returns: 0 if @error is set, otherwise a subtree registration id (never 0) - * that can be used with g_dbus_connection_unregister_subtree() . + * Returns: 0 if @error is set, otherwise a subtree registration ID (never 0) + * that can be used with g_dbus_connection_unregister_subtree() * Since: 2.26 */ @@ -16244,7 +16251,9 @@ * will be assigned by @connection and set on @message via * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the * serial number used will be written to this location prior to - * submitting the message to the underlying transport. + * submitting the message to the underlying transport. While it has a `volatile` + * qualifier, this is a historical artifact and the argument passed to it should + * not be `volatile`. * * If @connection is closed then the operation will fail with * %G_IO_ERROR_CLOSED. If @message is not well-formed, @@ -16284,7 +16293,9 @@ * will be assigned by @connection and set on @message via * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the * serial number used will be written to this location prior to - * submitting the message to the underlying transport. + * submitting the message to the underlying transport. While it has a `volatile` + * qualifier, this is a historical artifact and the argument passed to it should + * not be `volatile`. * * If @connection is closed then the operation will fail with * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will @@ -16354,7 +16365,9 @@ * will be assigned by @connection and set on @message via * g_dbus_message_set_serial(). If @out_serial is not %NULL, then the * serial number used will be written to this location prior to - * submitting the message to the underlying transport. + * submitting the message to the underlying transport. While it has a `volatile` + * qualifier, this is a historical artifact and the argument passed to it should + * not be `volatile`. * * If @connection is closed then the operation will fail with * %G_IO_ERROR_CLOSED. If @cancellable is canceled, the operation will @@ -16582,7 +16595,8 @@ * This function is typically only used in object mappings to put a * #GError on the wire. Regular applications should not use it. * - * Returns: A D-Bus error name (never %NULL). Free with g_free(). + * Returns: (transfer full) (not nullable): A D-Bus error name (never %NULL). + * Free with g_free(). * Since: 2.26 */ @@ -16598,8 +16612,8 @@ * (e.g. g_dbus_connection_call_finish()) unless * g_dbus_error_strip_remote_error() has been used on @error. * - * Returns: an allocated string or %NULL if the D-Bus error name - * could not be found. Free with g_free(). + * Returns: (nullable) (transfer full): an allocated string or %NULL if the + * D-Bus error name could not be found. Free with g_free(). * Since: 2.26 */ @@ -16649,7 +16663,7 @@ * #GError instances for applications. Regular applications should not use * it. * - * Returns: An allocated #GError. Free with g_error_free(). + * Returns: (transfer full): An allocated #GError. Free with g_error_free(). * Since: 2.26 */ @@ -16681,6 +16695,9 @@ * * Helper function for associating a #GError error domain with D-Bus error names. * + * While @quark_volatile has a `volatile` qualifier, this is a historical + * artifact and the argument passed to it should not be `volatile`. + * * Since: 2.26 */ diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index c4a42230..f7e7fc38 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -10692,7 +10692,7 @@ * To easily calculate @end_time, a combination of g_get_real_time() * and g_time_val_add() can be used. * - * Returns: data from the queue or %NULL, when no data is + * Returns: (nullable): data from the queue or %NULL, when no data is * received before @end_time. * Deprecated: use g_async_queue_timeout_pop(). */ @@ -10713,7 +10713,7 @@ * * This function must be called while holding the @queue's lock. * - * Returns: data from the queue or %NULL, when no data is + * Returns: (nullable): data from the queue or %NULL, when no data is * received before @end_time. * Deprecated: use g_async_queue_timeout_pop_unlocked(). */ @@ -10729,7 +10729,7 @@ * * If no data is received before the timeout, %NULL is returned. * - * Returns: data from the queue or %NULL, when no data is + * Returns: (nullable): data from the queue or %NULL, when no data is * received before the timeout. */ @@ -10746,7 +10746,7 @@ * * This function must be called while holding the @queue's lock. * - * Returns: data from the queue or %NULL, when no data is + * Returns: (nullable): data from the queue or %NULL, when no data is * received before the timeout. */ @@ -10758,7 +10758,7 @@ * Tries to pop data from the @queue. If no data is available, * %NULL is returned. * - * Returns: data from the queue or %NULL, when no data is + * Returns: (nullable): data from the queue or %NULL, when no data is * available immediately. */ @@ -10772,7 +10772,7 @@ * * This function must be called while holding the @queue's lock. * - * Returns: data from the queue or %NULL, when no data is + * Returns: (nullable): data from the queue or %NULL, when no data is * available immediately. */ @@ -10871,6 +10871,9 @@ * Before version 2.30, this function did not return a value * (but g_atomic_int_exchange_and_add() did, and had the same meaning). * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the add, signed * Since: 2.4 */ @@ -10889,6 +10892,9 @@ * Think of this operation as an atomic version of * `{ tmp = *atomic; *atomic &= val; return tmp; }`. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the operation, unsigned * Since: 2.30 */ @@ -10910,6 +10916,9 @@ * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: %TRUE if the exchange took place * Since: 2.4 */ @@ -10926,6 +10935,9 @@ * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: %TRUE if the resultant value is zero * Since: 2.4 */ @@ -10955,6 +10967,9 @@ * This call acts as a full compiler and hardware * memory barrier (before the get). * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of the integer * Since: 2.4 */ @@ -10970,6 +10985,9 @@ * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Since: 2.4 */ @@ -10987,6 +11005,9 @@ * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the operation, unsigned * Since: 2.30 */ @@ -11002,6 +11023,9 @@ * This call acts as a full compiler and hardware * memory barrier (after the set). * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Since: 2.4 */ @@ -11019,6 +11043,9 @@ * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the operation, unsigned * Since: 2.30 */ @@ -11036,6 +11063,9 @@ * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the add, signed * Since: 2.30 */ @@ -11054,6 +11084,9 @@ * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the operation, unsigned * Since: 2.30 */ @@ -11075,6 +11108,9 @@ * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: %TRUE if the exchange took place * Since: 2.4 */ @@ -11089,6 +11125,9 @@ * This call acts as a full compiler and hardware * memory barrier (before the get). * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of the pointer * Since: 2.4 */ @@ -11107,6 +11146,9 @@ * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the operation, unsigned * Since: 2.30 */ @@ -11122,6 +11164,9 @@ * This call acts as a full compiler and hardware * memory barrier (after the set). * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Since: 2.4 */ @@ -11139,6 +11184,9 @@ * * This call acts as a full compiler and hardware memory barrier. * + * While @atomic has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: the value of @atomic before the operation, unsigned * Since: 2.30 */ @@ -11997,7 +12045,7 @@ * In the event the URI cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * - * Returns: a newly allocated string or %NULL if the specified + * Returns: (transfer full): a newly allocated string or %NULL if the specified * URI cannot be found. * Since: 2.12 */ @@ -12074,7 +12122,7 @@ * event that the MIME type cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_INVALID_VALUE. * - * Returns: a newly allocated string or %NULL if the specified + * Returns: (transfer full): a newly allocated string or %NULL if the specified * URI cannot be found. * Since: 2.12 */ @@ -12138,7 +12186,7 @@ * In the event the URI cannot be found, %NULL is returned and * @error is set to #G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND. * - * Returns: a newly allocated string or %NULL if the specified + * Returns: (transfer full): a newly allocated string or %NULL if the specified * URI cannot be found. * Since: 2.12 */ @@ -12687,7 +12735,7 @@ * * This function outputs @bookmark as a string. * - * Returns: (array length=length) (element-type guint8): + * Returns: (transfer full) (array length=length) (element-type guint8): * a newly allocated string holding the contents of the #GBookmarkFile * Since: 2.12 */ @@ -13325,8 +13373,8 @@ * g_checksum_get_string() or g_checksum_get_digest(), the copied * checksum will be closed as well. * - * Returns: the copy of the passed #GChecksum. Use g_checksum_free() - * when finished using it. + * Returns: (transfer full): the copy of the passed #GChecksum. Use + * g_checksum_free() when finished using it. * Since: 2.16 */ @@ -13394,7 +13442,7 @@ * will be closed and it won't be possible to call g_checksum_update() * on it anymore. * - * Returns: (transfer full): the newly created #GChecksum, or %NULL. + * Returns: (transfer full) (nullable): the newly created #GChecksum, or %NULL. * Use g_checksum_free() to free the memory allocated by it. * Since: 2.16 */ @@ -13684,8 +13732,10 @@ * * The hexadecimal string returned will be in lower case. * - * Returns: the digest of the binary data as a string in hexadecimal. - * The returned string should be freed with g_free() when done using it. + * Returns: (transfer full) (nullable): the digest of the binary data as a + * string in hexadecimal, or %NULL if g_checksum_new() fails for + * @checksum_type. The returned string should be freed with g_free() when + * done using it. * Since: 2.34 */ @@ -13702,8 +13752,10 @@ * * The hexadecimal string returned will be in lower case. * - * Returns: the digest of the binary data as a string in hexadecimal. - * The returned string should be freed with g_free() when done using it. + * Returns: (transfer full) (nullable): the digest of the binary data as a + * string in hexadecimal, or %NULL if g_checksum_new() fails for + * @checksum_type. The returned string should be freed with g_free() when + * done using it. * Since: 2.16 */ @@ -13718,7 +13770,8 @@ * * The hexadecimal string returned will be in lower case. * - * Returns: the checksum as a hexadecimal string. The returned string + * Returns: (transfer full) (nullable): the checksum as a hexadecimal string, + * or %NULL if g_checksum_new() fails for @checksum_type. The returned string * should be freed with g_free() when done using it. * Since: 2.16 */ @@ -15212,8 +15265,8 @@ /** * g_date_time_compare: - * @dt1: (not nullable): first #GDateTime to compare - * @dt2: (not nullable): second #GDateTime to compare + * @dt1: (type GDateTime) (not nullable): first #GDateTime to compare + * @dt2: (type GDateTime) (not nullable): second #GDateTime to compare * * A comparison function for #GDateTimes that is suitable * as a #GCompareFunc. Both #GDateTimes must be non-%NULL. @@ -15241,8 +15294,8 @@ /** * g_date_time_equal: - * @dt1: (not nullable): a #GDateTime - * @dt2: (not nullable): a #GDateTime + * @dt1: (type GDateTime) (not nullable): a #GDateTime + * @dt2: (type GDateTime) (not nullable): a #GDateTime * * Checks to see if @dt1 and @dt2 are equal. * @@ -15629,7 +15682,7 @@ /** * g_date_time_hash: - * @datetime: (not nullable): a #GDateTime + * @datetime: (type GDateTime) (not nullable): a #GDateTime * * Hashes @datetime into a #guint, suitable for use within #GHashTable. * @@ -16708,7 +16761,7 @@ * @error: return location for a #GError, or %NULL * * Writes all of @contents to a file named @filename. This is a convenience - * wrapper around calling g_file_set_contents() with `flags` set to + * wrapper around calling g_file_set_contents_full() with `flags` set to * `G_FILE_SET_CONTENTS_CONSISTENT | G_FILE_SET_CONTENTS_ONLY_EXISTING` and * `mode` set to `0666`. * @@ -18852,8 +18905,8 @@ * string containing no uppercase letters and not ending with a * trailing dot. * - * Returns: an ASCII hostname, which must be freed, or %NULL if - * @hostname is in some way invalid. + * Returns: (nullable) (transfer full): an ASCII hostname, which must be freed, + * or %NULL if @hostname is in some way invalid. * Since: 2.22 */ @@ -18870,8 +18923,8 @@ * Of course if @hostname is not an internationalized hostname, then * the canonical presentation form will be entirely ASCII. * - * Returns: a UTF-8 hostname, which must be freed, or %NULL if - * @hostname is in some way invalid. + * Returns: (nullable) (transfer full): a UTF-8 hostname, which must be freed, + * or %NULL if @hostname is in some way invalid. * Since: 2.22 */ @@ -22448,7 +22501,7 @@ * * |[<!-- language="C" --> * #define NUM_TASKS 10 - * static volatile gint tasks_remaining = NUM_TASKS; + * static gint tasks_remaining = NUM_TASKS; // (atomic) * ... * * while (g_atomic_int_get (&tasks_remaining) != 0) @@ -24375,6 +24428,9 @@ * // use initialization_value here * ]| * + * While @location has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Returns: %TRUE if the initialization section should be entered, * %FALSE and blocks otherwise * Since: 2.14 @@ -24393,6 +24449,9 @@ * releases concurrent threads blocking in g_once_init_enter() on this * initialization variable. * + * While @location has a `volatile` qualifier, this is a historical artifact and + * the pointer passed to it should not be `volatile`. + * * Since: 2.14 */ @@ -25519,8 +25578,8 @@ * threads, use only the atomic g_ptr_array_ref() and g_ptr_array_unref() * functions. * - * Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL. - * The pointer array should be freed using g_free(). + * Returns: (transfer full) (nullable): the pointer array if @free_seg is + * %FALSE, otherwise %NULL. The pointer array should be freed using g_free(). */ @@ -34365,7 +34424,26 @@ * g_time_zone_new: * @identifier: (nullable): a timezone identifier * - * Creates a #GTimeZone corresponding to @identifier. + * A version of g_time_zone_new_identifier() which returns the UTC time zone + * if @identifier could not be parsed or loaded. + * + * If you need to check whether @identifier was loaded successfully, use + * g_time_zone_new_identifier(). + * + * Returns: (transfer full) (not nullable): the requested timezone + * Deprecated: 2.68: Use g_time_zone_new_identifier() instead, as it provides + * error reporting. Change your code to handle a potentially %NULL return + * value. + * Since: 2.26 + */ + + +/** + * g_time_zone_new_identifier: + * @identifier: (nullable): a timezone identifier + * + * Creates a #GTimeZone corresponding to @identifier. If @identifier cannot be + * parsed or loaded, %NULL is returned. * * @identifier can either be an RFC3339/ISO 8601 time offset or * something that would pass as a valid value for the `TZ` environment @@ -34430,8 +34508,9 @@ * You should release the return value by calling g_time_zone_unref() * when you are done with it. * - * Returns: the requested timezone - * Since: 2.26 + * Returns: (transfer full) (nullable): the requested timezone, or %NULL on + * failure + * Since: 2.68 */ diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index bbe32598..fd454260 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -811,6 +811,38 @@ /** + * g_binding_dup_source: + * @binding: a #GBinding + * + * Retrieves the #GObject instance used as the source of the binding. + * + * A #GBinding can outlive the source #GObject as the binding does not hold a + * strong reference to the source. If the source is destroyed before the + * binding then this function will return %NULL. + * + * Returns: (transfer full) (nullable): the source #GObject, or %NULL if the + * source does not exist any more. + * Since: 2.68 + */ + + +/** + * g_binding_dup_target: + * @binding: a #GBinding + * + * Retrieves the #GObject instance used as the target of the binding. + * + * A #GBinding can outlive the target #GObject as the binding does not hold a + * strong reference to the target. If the target is destroyed before the + * binding then this function will return %NULL. + * + * Returns: (transfer full) (nullable): the target #GObject, or %NULL if the + * target does not exist any more. + * Since: 2.68 + */ + + +/** * g_binding_get_flags: * @binding: a #GBinding * @@ -831,8 +863,14 @@ * strong reference to the source. If the source is destroyed before the * binding then this function will return %NULL. * + * Use g_binding_dup_source() if the source or binding are used from different + * threads as otherwise the pointer returned from this function might become + * invalid if the source is finalized from another thread in the meantime. + * * Returns: (transfer none) (nullable): the source #GObject, or %NULL if the * source does not exist any more. + * Deprecated: 2.68: Use g_binding_dup_source() for a safer version of this + * function. * Since: 2.26 */ @@ -859,8 +897,14 @@ * strong reference to the target. If the target is destroyed before the * binding then this function will return %NULL. * + * Use g_binding_dup_target() if the target or binding are used from different + * threads as otherwise the pointer returned from this function might become + * invalid if the target is finalized from another thread in the meantime. + * * Returns: (transfer none) (nullable): the target #GObject, or %NULL if the * target does not exist any more. + * Deprecated: 2.68: Use g_binding_dup_target() for a safer version of this + * function. * Since: 2.26 */ @@ -885,9 +929,13 @@ * property expressed by @binding. * * This function will release the reference that is being held on - * the @binding instance; if you want to hold on to the #GBinding instance - * after calling g_binding_unbind(), you will need to hold a reference - * to it. + * the @binding instance if the binding is still bound; if you want to hold on + * to the #GBinding instance after calling g_binding_unbind(), you will need + * to hold a reference to it. + * + * Note however that this function does not take ownership of @binding, it + * only unrefs the reference that was initially created by + * g_object_bind_property() and is owned by the binding. * * Since: 2.38 */ @@ -2168,7 +2216,7 @@ * * Returns the #GEnumValue for a value. * - * Returns: (transfer none): the #GEnumValue for @value, or %NULL + * Returns: (transfer none) (nullable): the #GEnumValue for @value, or %NULL * if @value is not a member of the enumeration */ @@ -2180,7 +2228,7 @@ * * Looks up a #GEnumValue by name. * - * Returns: (transfer none): the #GEnumValue with name @name, + * Returns: (transfer none) (nullable): the #GEnumValue with name @name, * or %NULL if the enumeration doesn't have a member * with that name */ @@ -2193,7 +2241,7 @@ * * Looks up a #GEnumValue by nickname. * - * Returns: (transfer none): the #GEnumValue with nickname @nick, + * Returns: (transfer none) (nullable): the #GEnumValue with nickname @nick, * or %NULL if the enumeration doesn't have a member * with that nickname */ @@ -2253,7 +2301,7 @@ * * Returns the first #GFlagsValue which is set in @value. * - * Returns: (transfer none): the first #GFlagsValue which is set in + * Returns: (transfer none) (nullable): the first #GFlagsValue which is set in * @value, or %NULL if none is set */ @@ -2265,7 +2313,7 @@ * * Looks up a #GFlagsValue by name. * - * Returns: (transfer none): the #GFlagsValue with name @name, + * Returns: (transfer none) (nullable): the #GFlagsValue with name @name, * or %NULL if there is no flag with that name */ @@ -2277,7 +2325,7 @@ * * Looks up a #GFlagsValue by nickname. * - * Returns: (transfer none): the #GFlagsValue with nickname @nick, + * Returns: (transfer none) (nullable): the #GFlagsValue with nickname @nick, * or %NULL if there is no flag with that nickname */ @@ -2403,6 +2451,13 @@ * @source and the @target you can just call g_object_unref() on the returned * #GBinding instance. * + * Removing the binding by calling g_object_unref() on it must only be done if + * the binding, @source and @target are only used from a single thread and it + * is clear that both @source and @target outlive the binding. Especially it + * is not safe to rely on this if the binding, @source or @target can be + * finalized from different threads. Keep another reference to the binding and + * use g_binding_unbind() instead to be on the safe side. + * * A #GObject can have multiple bindings. * * Returns: (transfer none): the #GBinding instance representing the @@ -3494,7 +3549,7 @@ * @data: extra data to pass to notify * * Adds a weak reference callback to an object. Weak references are - * used for notification when an object is finalized. They are called + * used for notification when an object is disposed. They are called * "weak references" because they allow you to safely hold a pointer * to an object without calling g_object_ref() (g_object_ref() adds a * strong reference, that is, forces the object to stay alive). @@ -3648,7 +3703,7 @@ * * Get the short description of a #GParamSpec. * - * Returns: the short description of @pspec. + * Returns: (nullable): the short description of @pspec. */ @@ -3706,7 +3761,7 @@ * * Gets back user data pointers stored via g_param_spec_set_qdata(). * - * Returns: (transfer none): the user data pointer set, or %NULL + * Returns: (transfer none) (nullable): the user data pointer set, or %NULL */ @@ -3723,7 +3778,7 @@ * for an example of the use of this capability. * * Since: 2.4 - * Returns: (transfer none): paramspec to which requests on this + * Returns: (transfer none) (nullable): paramspec to which requests on this * paramspec should be redirected, or %NULL if none. */ @@ -3803,7 +3858,7 @@ * @blurb, which should be a somewhat longer description, suitable for * e.g. a tooltip. The @nick and @blurb should ideally be localized. * - * Returns: (type GObject.ParamSpec): a newly allocated #GParamSpec instance + * Returns: (type GObject.ParamSpec): (transfer full): a newly allocated #GParamSpec instance */ @@ -3909,7 +3964,7 @@ /** * g_param_spec_pool_insert: * @pool: a #GParamSpecPool. - * @pspec: the #GParamSpec to insert + * @pspec: (transfer none) (not nullable): the #GParamSpec to insert * @owner_type: a #GType identifying the owner of @pspec * * Inserts a #GParamSpec in the pool. @@ -3955,7 +4010,7 @@ * * Looks up a #GParamSpec in the pool. * - * Returns: (transfer none): The found #GParamSpec, or %NULL if no + * Returns: (transfer none) (nullable): The found #GParamSpec, or %NULL if no * matching #GParamSpec was found. */ @@ -3971,14 +4026,14 @@ * property name, like "GtkContainer:border-width". This feature is * deprecated, so you should always set @type_prefixing to %FALSE. * - * Returns: (transfer none): a newly allocated #GParamSpecPool. + * Returns: (transfer full): a newly allocated #GParamSpecPool. */ /** * g_param_spec_pool_remove: * @pool: a #GParamSpecPool - * @pspec: the #GParamSpec to remove + * @pspec: (transfer none) (not nullable): the #GParamSpec to remove * * Removes a #GParamSpec from the pool. */ @@ -3986,11 +4041,11 @@ /** * g_param_spec_ref: (skip) - * @pspec: a valid #GParamSpec + * @pspec: (transfer none) (not nullable): a valid #GParamSpec * * Increments the reference count of @pspec. * - * Returns: the #GParamSpec that was passed into this function + * Returns: (transfer full) (not nullable): the #GParamSpec that was passed into this function */ @@ -4001,7 +4056,7 @@ * Convenience function to ref and sink a #GParamSpec. * * Since: 2.10 - * Returns: the #GParamSpec that was passed into this function + * Returns: (transfer full) (not nullable): the #GParamSpec that was passed into this function */ @@ -4009,7 +4064,7 @@ * g_param_spec_set_qdata: * @pspec: the #GParamSpec to set store a user data pointer * @quark: a #GQuark, naming the user data pointer - * @data: an opaque user data pointer + * @data: (nullable): an opaque user data pointer * * Sets an opaque, named pointer on a #GParamSpec. The name is * specified through a #GQuark (retrieved e.g. via @@ -4024,8 +4079,8 @@ * g_param_spec_set_qdata_full: (skip) * @pspec: the #GParamSpec to set store a user data pointer * @quark: a #GQuark, naming the user data pointer - * @data: an opaque user data pointer - * @destroy: function to invoke with @data as argument, when @data needs to + * @data: (nullable): an opaque user data pointer + * @destroy: (nullable): function to invoke with @data as argument, when @data needs to * be freed * * This function works like g_param_spec_set_qdata(), but in addition, @@ -4060,7 +4115,7 @@ * function (if any was set). Usually, calling this function is only * required to update user data pointers with a destroy notifier. * - * Returns: (transfer none): the user data pointer set, or %NULL + * Returns: (transfer none) (nullable): the user data pointer set, or %NULL */ @@ -4364,9 +4419,9 @@ * g_signal_add_emission_hook: * @signal_id: the signal identifier, as returned by g_signal_lookup(). * @detail: the detail on which to call the hook. - * @hook_func: a #GSignalEmissionHook function. - * @hook_data: user data for @hook_func. - * @data_destroy: a #GDestroyNotify for @hook_data. + * @hook_func: (not nullable): a #GSignalEmissionHook function. + * @hook_data: (nullable): user data for @hook_func. + * @data_destroy: (nullable): a #GDestroyNotify for @hook_data. * * Adds an emission hook for a signal, which will get called for any emission * of that signal, independent of the instance. This is possible only @@ -4411,7 +4466,7 @@ * g_signal_connect_closure: * @instance: (type GObject.Object): the instance to connect to. * @detailed_signal: a string of the form "signal-name::detail". - * @closure: the closure to connect. + * @closure: (not nullable): the closure to connect. * @after: whether the handler should be called before or after the * default handler of the signal. * @@ -4426,7 +4481,7 @@ * @instance: (type GObject.Object): the instance to connect to. * @signal_id: the id of the signal. * @detail: the detail. - * @closure: the closure to connect. + * @closure: (not nullable): the closure to connect. * @after: whether the handler should be called before or after the * default handler of the signal. * @@ -4440,9 +4495,9 @@ * g_signal_connect_data: * @instance: (type GObject.Object): the instance to connect to. * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: the #GCallback to connect. - * @data: data to pass to @c_handler calls. - * @destroy_data: a #GClosureNotify for @data. + * @c_handler: (not nullable): the #GCallback to connect. + * @data: (nullable): data to pass to @c_handler calls. + * @destroy_data: (nullable): a #GClosureNotify for @data. * @connect_flags: a combination of #GConnectFlags. * * Connects a #GCallback function to a signal for a particular object. Similar @@ -4549,7 +4604,8 @@ * * Returns the invocation hint of the innermost signal emission of instance. * - * Returns: (transfer none): the invocation hint of the innermost signal emission. + * Returns: (transfer none) (nullable): the invocation hint of the innermost + * signal emission, or %NULL if not found. */ @@ -4592,7 +4648,7 @@ * @detail: Signal detail the handler has to be connected to. * @closure: (nullable): The closure the handler will invoke. * @func: The C closure callback of the handler (useless for non-C closures). - * @data: The closure data of the handler's closure. + * @data: (nullable): The closure data of the handler's closure. * * Finds the first signal handler that matches certain selection criteria. * The criteria mask is passed as an OR-ed combination of #GSignalMatchType @@ -4645,7 +4701,7 @@ * @detail: Signal detail the handlers have to be connected to. * @closure: (nullable): The closure the handlers will invoke. * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. + * @data: (nullable): The closure data of the handlers' closures. * * Blocks all handlers on an instance that match a certain selection criteria. * The criteria mask is passed as an OR-ed combination of #GSignalMatchType @@ -4678,7 +4734,7 @@ * @detail: Signal detail the handlers have to be connected to. * @closure: (nullable): The closure the handlers will invoke. * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. + * @data: (nullable): The closure data of the handlers' closures. * * Disconnects all handlers on an instance that match a certain * selection criteria. The criteria mask is passed as an OR-ed @@ -4702,7 +4758,7 @@ * @detail: Signal detail the handlers have to be connected to. * @closure: (nullable): The closure the handlers will invoke. * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. + * @data: (nullable): The closure data of the handlers' closures. * * Unblocks all handlers on an instance that match a certain selection * criteria. The criteria mask is passed as an OR-ed combination of @@ -4804,7 +4860,7 @@ * * Two different signals may have the same name, if they have differing types. * - * Returns: the signal name, or %NULL if the signal number was invalid. + * Returns: (nullable): the signal name, or %NULL if the signal number was invalid. */ @@ -4819,8 +4875,8 @@ * @class_offset: The offset of the function pointer in the class structure * for this type. Used to invoke a class method generically. Pass 0 to * not associate a class method slot with this signal. - * @accumulator: the accumulator for this signal; may be %NULL. - * @accu_data: user data for the @accumulator. + * @accumulator: (nullable): the accumulator for this signal; may be %NULL. + * @accu_data: (nullable): user data for the @accumulator. * @c_marshaller: (nullable): the function to translate arrays of parameter * values to signal emissions into C language callback invocations or %NULL. * @return_type: the type of return value, or #G_TYPE_NONE for a signal @@ -4865,11 +4921,11 @@ * @signal_flags: a combination of #GSignalFlags specifying detail of when * the default handler is to be invoked. You should at least specify * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_handler: a #GCallback which acts as class implementation of + * @class_handler: (nullable): a #GCallback which acts as class implementation of * this signal. Used to invoke a class method generically. Pass %NULL to * not associate a class method with this signal. - * @accumulator: the accumulator for this signal; may be %NULL. - * @accu_data: user data for the @accumulator. + * @accumulator: (nullable): the accumulator for this signal; may be %NULL. + * @accu_data: (nullable): user data for the @accumulator. * @c_marshaller: (nullable): the function to translate arrays of parameter * values to signal emissions into C language callback invocations or %NULL. * @return_type: the type of return value, or #G_TYPE_NONE for a signal @@ -4907,9 +4963,9 @@ * @signal_flags: a combination of #GSignalFlags specifying detail of when * the default handler is to be invoked. You should at least specify * %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_closure: The closure to invoke on signal emission; may be %NULL. - * @accumulator: the accumulator for this signal; may be %NULL. - * @accu_data: user data for the @accumulator. + * @class_closure: (nullable): The closure to invoke on signal emission; may be %NULL. + * @accumulator: (nullable): the accumulator for this signal; may be %NULL. + * @accu_data: (nullable): user data for the @accumulator. * @c_marshaller: (nullable): the function to translate arrays of parameter * values to signal emissions into C language callback invocations or %NULL. * @return_type: the type of return value, or #G_TYPE_NONE for a signal @@ -4939,15 +4995,15 @@ * @class_closure: (nullable): The closure to invoke on signal emission; * may be %NULL * @accumulator: (nullable): the accumulator for this signal; may be %NULL - * @accu_data: user data for the @accumulator + * @accu_data: (nullable): user data for the @accumulator * @c_marshaller: (nullable): the function to translate arrays of * parameter values to signal emissions into C language callback * invocations or %NULL * @return_type: the type of return value, or #G_TYPE_NONE for a signal * without a return value * @n_params: the length of @param_types - * @param_types: (array length=n_params): an array of types, one for - * each parameter + * @param_types: (array length=n_params) (nullable): an array of types, one for + * each parameter (may be %NULL if @n_params is zero) * * Creates a new signal. (This is usually done in the class initializer.) * @@ -5015,7 +5071,7 @@ /** * g_signal_query: * @signal_id: The signal id of the signal to query information for. - * @query: (out caller-allocates): A user provided structure that is + * @query: (out caller-allocates) (not optional): A user provided structure that is * filled in with constant values upon success. * * Queries the signal system for in-depth information about a @@ -5765,8 +5821,8 @@ /** * g_type_is_a: - * @type: type to check anchestry for - * @is_a_type: possible anchestor of @type or interface that @type + * @type: type to check ancestry for + * @is_a_type: possible ancestor of @type or interface that @type * could conform to * * If @is_a_type is a derivable type, check whether @type is a @@ -5935,7 +5991,7 @@ * be used to determine the types and order in which the leaf type is * descended from the root type. * - * Returns: immediate child of @root_type and anchestor of @leaf_type + * Returns: immediate child of @root_type and ancestor of @leaf_type */ @@ -6319,8 +6375,8 @@ * Get the contents of a %G_TYPE_PARAM #GValue, increasing its * reference count. * - * Returns: #GParamSpec content of @value, should be unreferenced when - * no longer needed. + * Returns: (transfer full): #GParamSpec content of @value, should be + * unreferenced when no longer needed. */ |