gir: Update annotations from glib git master

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