gir: Update annotations from GLib git master

3 files changed, 79 insertions, 63 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index fa8c679d..97a9597b 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -5912,7 +5912,7 @@
  * ## An example for file descriptor passing # {#gdbus-unix-fd-client}
  *
  * Here is an example for passing UNIX file descriptors:
- * [gdbus-unix-fd-client.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-unix-fd-client.c)
+ * [gdbus-unix-fd-client.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-unix-fd-client.c)
  *
  * ## An example for exporting a GObject # {#gdbus-export}
  *
@@ -10705,7 +10705,7 @@
  * _g_freedesktop_dbus_call_add_match:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_rule: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -10733,7 +10733,7 @@
  * _g_freedesktop_dbus_call_add_match_sync:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_rule: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.AddMatch">AddMatch()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -10748,7 +10748,7 @@
  * _g_freedesktop_dbus_call_get_connection_selinux_security_context:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -10778,7 +10778,7 @@
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
  * @out_security_context: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionSELinuxSecurityContext">GetConnectionSELinuxSecurityContext()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -10793,7 +10793,7 @@
  * _g_freedesktop_dbus_call_get_connection_unix_process_id:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -10823,7 +10823,7 @@
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
  * @out_pid: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixProcessID">GetConnectionUnixProcessID()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -10838,7 +10838,7 @@
  * _g_freedesktop_dbus_call_get_connection_unix_user:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -10868,7 +10868,7 @@
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
  * @out_uid: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetConnectionUnixUser">GetConnectionUnixUser()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -10882,7 +10882,7 @@
 /**
  * _g_freedesktop_dbus_call_get_id:
  * @proxy: A #_GFreedesktopDBusProxy.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -10911,7 +10911,7 @@
  * _g_freedesktop_dbus_call_get_id_sync:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @out_unique_id: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetId">GetId()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -10926,7 +10926,7 @@
  * _g_freedesktop_dbus_call_get_name_owner:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -10956,7 +10956,7 @@
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
  * @out_unique_name: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.GetNameOwner">GetNameOwner()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -10970,7 +10970,7 @@
 /**
  * _g_freedesktop_dbus_call_hello:
  * @proxy: A #_GFreedesktopDBusProxy.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -10999,7 +10999,7 @@
  * _g_freedesktop_dbus_call_hello_sync:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @out_assigned_name: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.Hello">Hello()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -11013,7 +11013,7 @@
 /**
  * _g_freedesktop_dbus_call_list_activatable_names:
  * @proxy: A #_GFreedesktopDBusProxy.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -11028,7 +11028,7 @@
 /**
  * _g_freedesktop_dbus_call_list_activatable_names_finish:
  * @proxy: A #_GFreedesktopDBusProxy.
- * @out_activatable_names: (out): Return location for return parameter or %NULL to ignore.
+ * @out_activatable_names: (out) (array zero-terminated=1): Return location for return parameter or %NULL to ignore.
  * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_activatable_names().
  * @error: Return location for error or %NULL.
  *
@@ -11041,8 +11041,8 @@
 /**
  * _g_freedesktop_dbus_call_list_activatable_names_sync:
  * @proxy: A #_GFreedesktopDBusProxy.
- * @out_activatable_names: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @out_activatable_names: (out) (array zero-terminated=1): Return location for return parameter or %NULL to ignore.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListActivatableNames">ListActivatableNames()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -11056,7 +11056,7 @@
 /**
  * _g_freedesktop_dbus_call_list_names:
  * @proxy: A #_GFreedesktopDBusProxy.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -11071,7 +11071,7 @@
 /**
  * _g_freedesktop_dbus_call_list_names_finish:
  * @proxy: A #_GFreedesktopDBusProxy.
- * @out_names: (out): Return location for return parameter or %NULL to ignore.
+ * @out_names: (out) (array zero-terminated=1): Return location for return parameter or %NULL to ignore.
  * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_names().
  * @error: Return location for error or %NULL.
  *
@@ -11084,8 +11084,8 @@
 /**
  * _g_freedesktop_dbus_call_list_names_sync:
  * @proxy: A #_GFreedesktopDBusProxy.
- * @out_names: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @out_names: (out) (array zero-terminated=1): Return location for return parameter or %NULL to ignore.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListNames">ListNames()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -11100,7 +11100,7 @@
  * _g_freedesktop_dbus_call_list_queued_owners:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -11115,7 +11115,7 @@
 /**
  * _g_freedesktop_dbus_call_list_queued_owners_finish:
  * @proxy: A #_GFreedesktopDBusProxy.
- * @out_queued_owners: (out): Return location for return parameter or %NULL to ignore.
+ * @out_queued_owners: (out) (array zero-terminated=1): Return location for return parameter or %NULL to ignore.
  * @res: The #GAsyncResult obtained from the #GAsyncReadyCallback passed to _g_freedesktop_dbus_call_list_queued_owners().
  * @error: Return location for error or %NULL.
  *
@@ -11129,8 +11129,8 @@
  * _g_freedesktop_dbus_call_list_queued_owners_sync:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
- * @out_queued_owners: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @out_queued_owners: (out) (array zero-terminated=1): Return location for return parameter or %NULL to ignore.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ListQueuedOwners">ListQueuedOwners()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -11145,7 +11145,7 @@
  * _g_freedesktop_dbus_call_name_has_owner:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -11175,7 +11175,7 @@
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
  * @out_has_owner: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.NameHasOwner">NameHasOwner()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -11190,7 +11190,7 @@
  * _g_freedesktop_dbus_call_release_name:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -11220,7 +11220,7 @@
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
  * @out_value: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReleaseName">ReleaseName()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -11234,7 +11234,7 @@
 /**
  * _g_freedesktop_dbus_call_reload_config:
  * @proxy: A #_GFreedesktopDBusProxy.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -11261,7 +11261,7 @@
 /**
  * _g_freedesktop_dbus_call_reload_config_sync:
  * @proxy: A #_GFreedesktopDBusProxy.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.ReloadConfig">ReloadConfig()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -11276,7 +11276,7 @@
  * _g_freedesktop_dbus_call_remove_match:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_rule: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -11304,7 +11304,7 @@
  * _g_freedesktop_dbus_call_remove_match_sync:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_rule: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RemoveMatch">RemoveMatch()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -11320,7 +11320,7 @@
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
  * @arg_flags: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -11351,7 +11351,7 @@
  * @arg_name: Argument to pass with the method invocation.
  * @arg_flags: Argument to pass with the method invocation.
  * @out_value: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.RequestName">RequestName()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -11367,7 +11367,7 @@
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_name: Argument to pass with the method invocation.
  * @arg_flags: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -11398,7 +11398,7 @@
  * @arg_name: Argument to pass with the method invocation.
  * @arg_flags: Argument to pass with the method invocation.
  * @out_value: (out): Return location for return parameter or %NULL to ignore.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.StartServiceByName">StartServiceByName()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -11413,7 +11413,7 @@
  * _g_freedesktop_dbus_call_update_activation_environment:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_environment: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied or %NULL.
  * @user_data: User data to pass to @callback.
  *
@@ -11441,7 +11441,7 @@
  * _g_freedesktop_dbus_call_update_activation_environment_sync:
  * @proxy: A #_GFreedesktopDBusProxy.
  * @arg_environment: Argument to pass with the method invocation.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL.
  *
  * Synchronously invokes the <link linkend="gdbus-method-org-freedesktop-DBus.UpdateActivationEnvironment">UpdateActivationEnvironment()</link> D-Bus method on @proxy. The calling thread is blocked until a reply is received.
@@ -11692,7 +11692,7 @@
 
 /**
  * _g_freedesktop_dbus_override_properties:
- * @klass: The class structure for a #GObject<!-- -->-derived class.
+ * @klass: The class structure for a #GObject derived class.
  * @property_id_begin: The property id to assign to the first overridden property.
  *
  * Overrides all #GObject properties in the #_GFreedesktopDBus interface for a concrete class.
@@ -11706,9 +11706,9 @@
  * _g_freedesktop_dbus_proxy_new:
  * @connection: A #GDBusConnection.
  * @flags: Flags from the #GDBusProxyFlags enumeration.
- * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
+ * @name: (nullable): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
  * @object_path: An object path.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
  * @user_data: User data to pass to @callback.
  *
@@ -11738,7 +11738,7 @@
  * @flags: Flags from the #GDBusProxyFlags enumeration.
  * @name: A bus name (well-known or unique).
  * @object_path: An object path.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @callback: A #GAsyncReadyCallback to call when the request is satisfied.
  * @user_data: User data to pass to @callback.
  *
@@ -11768,7 +11768,7 @@
  * @flags: Flags from the #GDBusProxyFlags enumeration.
  * @name: A bus name (well-known or unique).
  * @object_path: An object path.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL
  *
  * Like _g_freedesktop_dbus_proxy_new_sync() but takes a #GBusType instead of a #GDBusConnection.
@@ -11785,9 +11785,9 @@
  * _g_freedesktop_dbus_proxy_new_sync:
  * @connection: A #GDBusConnection.
  * @flags: Flags from the #GDBusProxyFlags enumeration.
- * @name: (allow-none): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
+ * @name: (nullable): A bus name (well-known or unique) or %NULL if @connection is not a message bus connection.
  * @object_path: An object path.
- * @cancellable: (allow-none): A #GCancellable or %NULL.
+ * @cancellable: (nullable): A #GCancellable or %NULL.
  * @error: Return location for error or %NULL
  *
  * Synchronously creates a proxy for the D-Bus interface <link linkend="gdbus-interface-org-freedesktop-DBus.top_of_page">org.freedesktop.DBus</link>. See g_dbus_proxy_new_sync() for more details.
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 1651e312..17d30b09 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -12120,7 +12120,7 @@
  * @bytes: (nullable): a #GBytes
  *
  * Releases a reference on @bytes.  This may result in the bytes being
- * freed.
+ * freed. If @bytes is %NULL, it will return immediately.
  *
  * Since: 2.32
  */
@@ -14146,7 +14146,8 @@
  *   for the specifier.
  *
  * Returns: a newly allocated string formatted to the requested format
- *     or %NULL in the case that there was an error. The string
+ *     or %NULL in the case that there was an error (such as a format specifier
+ *     not being supported in the current locale). The string
  *     should be freed with g_free().
  * Since: 2.26
  */
@@ -27608,7 +27609,8 @@
  *     first element comes before the second, or a positive value if
  *     the first element comes after the second.
  *
- * Sorts a #GSList using the given comparison function.
+ * Sorts a #GSList using the given comparison function. The algorithm
+ * used is a stable sort.
  *
  * Returns: the start of the sorted #GSList
  */
@@ -28015,17 +28017,15 @@
  * g_source_remove:
  * @tag: the ID of the source to remove.
  *
- * Removes the source with the given id from the default main context.
+ * Removes the source with the given ID from the default main context. You must
+ * use g_source_destroy() for sources added to a non-default main context.
  *
- * The id of a #GSource is given by g_source_get_id(), or will be
+ * The ID of a #GSource is given by g_source_get_id(), or will be
  * returned by the functions g_source_attach(), g_idle_add(),
  * g_idle_add_full(), g_timeout_add(), g_timeout_add_full(),
  * g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and
  * g_io_add_watch_full().
  *
- * See also g_source_destroy(). You must use g_source_destroy() for sources
- * added to a non-default main context.
- *
  * It is a programmer error to attempt to remove a non-existent source.
  *
  * More specifically: source IDs can be reissued after a source has been
@@ -28264,7 +28264,7 @@
  * Note that if you have a pair of sources where the ready time of one
  * suggests that it will be delivered first but the priority for the
  * other suggests that it would be delivered first, and the ready time
- * for both sources is reached during the same main context iteration
+ * for both sources is reached during the same main context iteration,
  * then the order of dispatch is undefined.
  *
  * It is a no-op to call this function on a #GSource which has already been
@@ -35257,6 +35257,13 @@
  * data from untrusted sources and you want to ensure your serialised
  * output is definitely in normal form.
  *
+ * If @value is already in normal form, a new reference will be returned
+ * (which will be floating if @value is floating). If it is not in normal form,
+ * the newly created #GVariant will be returned with a single non-floating
+ * reference. Typically, g_variant_take_ref() should be called on the return
+ * value from this function to guarantee ownership of a single non-floating
+ * reference to it.
+ *
  * Returns: (transfer full): a trusted #GVariant
  * Since: 2.24
  */
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index f94bdb49..596e2685 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -265,8 +265,8 @@
  * to a function and maybe a data argument, and the marshaller
  * converts between #GValue and native C types. The GObject
  * library provides the #GCClosure type for this purpose. Bindings for
- * other languages need marshallers which convert between #GValue<!--
- * -->s and suitable representations in the runtime of the language in
+ * other languages need marshallers which convert between #GValues
+ * and suitable representations in the runtime of the language in
  * order to use functions written in that languages as callbacks.
  *
  * Within GObject, closures play an important role in the
@@ -3126,6 +3126,11 @@
  *
  * Increases the reference count of @object.
  *
+ * Since GLib 2.56, if `GLIB_VERSION_MAX_ALLOWED` is 2.56 or greater, the type
+ * of @object will be propagated to the return type (using the GCC typeof()
+ * extension), so any casting the caller needs to do on the return type must be
+ * explicit.
+ *
  * Returns: (type GObject.Object) (transfer none): the same @object
  */
 
@@ -3143,6 +3148,9 @@
  * count unchanged.  If the object is not floating, then this call
  * adds a new normal reference increasing the reference count by one.
  *
+ * Since GLib 2.56, the type of @object will be propagated to the return type
+ * under the same conditions as for g_object_ref().
+ *
  * Since: 2.10
  * Returns: (type GObject.Object) (transfer none): @object
  */
@@ -6245,10 +6253,11 @@
  * g_value_dup_variant:
  * @value: a valid #GValue of type %G_TYPE_VARIANT
  *
- * Get the contents of a variant #GValue, increasing its refcount.
+ * Get the contents of a variant #GValue, increasing its refcount. The returned
+ * #GVariant is never floating.
  *
- * Returns: variant contents of @value, should be unrefed using
- *   g_variant_unref() when no longer needed
+ * Returns: (transfer full) (nullable): variant contents of @value (may be %NULL);
+ *    should be unreffed using g_variant_unref() when no longer needed
  * Since: 2.26
  */
 
@@ -6476,7 +6485,7 @@
  *
  * Get the contents of a variant #GValue.
  *
- * Returns: variant contents of @value
+ * Returns: (nullable): variant contents of @value (may be %NULL)
  * Since: 2.26
  */