[gobject-introspection] gir: Update annotations from glib git master

[Rico Tzschichholz <ricotz src gnome org>]

commit 5ed5b1ed30938dbe70e50feffa56ee5ee47696d2
Author: Rico Tzschichholz <ricotz ubuntu com>
Date:   Sun Jan 31 13:21:35 2021 +0100

    gir: Update annotations from glib git master

 gir/gio-2.0.c     | 162 ++++++++++++++++++++++++++++++++----
 gir/glib-2.0.c    | 240 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 gir/gobject-2.0.c |  33 ++++----
 3 files changed, 386 insertions(+), 49 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index f3f865f2..9de34cd9 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -7608,12 +7608,16 @@
  * the xmllint executable, or xmllint must be in the `PATH`; otherwise
  * the preprocessing step is skipped.
  *
- * `to-pixdata` which will use the gdk-pixbuf-pixdata command to convert
- * images to the GdkPixdata format, which allows you to create pixbufs directly using the data inside
- * the resource file, rather than an (uncompressed) copy of it. For this, the gdk-pixbuf-pixdata
- * program must be in the PATH, or the `GDK_PIXBUF_PIXDATA` environment variable must be
- * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will
- * abort.
+ * `to-pixdata` (deprecated since gdk-pixbuf 2.32) which will use the
+ * `gdk-pixbuf-pixdata` command to convert images to the #GdkPixdata format,
+ * which allows you to create pixbufs directly using the data inside the
+ * resource file, rather than an (uncompressed) copy of it. For this, the
+ * `gdk-pixbuf-pixdata` program must be in the `PATH`, or the
+ * `GDK_PIXBUF_PIXDATA` environment variable must be set to the full path to the
+ * `gdk-pixbuf-pixdata` executable; otherwise the resource compiler will abort.
+ * `to-pixdata` has been deprecated since gdk-pixbuf 2.32, as #GResource
+ * supports embedding modern image formats just as well. Instead of using it,
+ * embed a PNG or SVG file in your #GResource.
  *
  * `json-stripblanks` which will use the `json-glib-format` command to strip
  * ignorable whitespace from the JSON file. For this to work, the
@@ -7691,7 +7695,7 @@
  * replace resources in the program or library, without recompiling, for debugging or quick hacking and 
testing
  * purposes. Since GLib 2.50, it is possible to use the `G_RESOURCE_OVERLAYS` environment variable to 
selectively overlay
  * resources with replacements from the filesystem.  It is a %G_SEARCHPATH_SEPARATOR-separated list of 
substitutions to perform
- * during resource lookups.
+ * during resource lookups. It is ignored when running in a setuid process.
  *
  * A substitution has the form
  *
@@ -10235,10 +10239,11 @@
  * be called on each candidate implementation after construction, to
  * check if it is actually usable or not.
  *
- * The result is cached after it is generated the first time, and
+ * The result is cached after it is generated the first time (but the cache does
+ * not keep a strong reference to the object), and
  * the function is thread-safe.
  *
- * Returns: (transfer none): an object implementing
+ * Returns: (transfer full) (nullable): an object implementing
  *     @extension_point, or %NULL if there are no usable
  *     implementations.
  */
@@ -10497,6 +10502,33 @@
  * parameters then @parameter must be %NULL.  See
  * g_action_group_get_action_parameter_type().
  *
+ * If the #GActionGroup implementation supports asynchronous remote
+ * activation over D-Bus, this call may return before the relevant
+ * D-Bus traffic has been sent, or any replies have been received. In
+ * order to block on such asynchronous activation calls,
+ * g_dbus_connection_flush() should be called prior to the code, which
+ * depends on the result of the action activation. Without flushing
+ * the D-Bus connection, there is no guarantee that the action would
+ * have been activated.
+ *
+ * The following code which runs in a remote app instance, shows an
+ * example of a "quit" action being activated on the primary app
+ * instance over D-Bus. Here g_dbus_connection_flush() is called
+ * before `exit()`. Without g_dbus_connection_flush(), the "quit" action
+ * may fail to be activated on the primary instance.
+ *
+ * |[<!-- language="C" -->
+ * // call "quit" action on primary instance
+ * g_action_group_activate_action (G_ACTION_GROUP (app), "quit", NULL);
+ *
+ * // make sure the action is activated now
+ * g_dbus_connection_flush (...);
+ *
+ * g_debug ("application has been terminated. exiting.");
+ *
+ * exit (0);
+ * ]|
+ *
  * Since: 2.28
  */
 
@@ -11001,7 +11033,7 @@
 
 
 /**
- * g_app_info_get_commandline:
+ * g_app_info_get_commandline: (virtual get_commandline)
  * @appinfo: a #GAppInfo
  *
  * Gets the commandline with which the application will be
@@ -11065,7 +11097,7 @@
 
 
 /**
- * g_app_info_get_executable:
+ * g_app_info_get_executable: (virtual get_executable)
  * @appinfo: a #GAppInfo
  *
  * Gets the executable's name for the installed application.
@@ -16761,6 +16793,43 @@
  */
 
 
+/**
+ * g_dbus_escape_object_path:
+ * @s: the string to escape
+ *
+ * This is a language binding friendly version of g_dbus_escape_object_path_bytestring().
+ *
+ * Returns: an escaped version of @s. Free with g_free().
+ * Since: 2.68
+ */
+
+
+/**
+ * g_dbus_escape_object_path_bytestring:
+ * @bytes: (array zero-terminated=1) (element-type guint8): the string of bytes to escape
+ *
+ * Escapes @bytes for use in a D-Bus object path component.
+ * @bytes is an array of zero or more nonzero bytes in an
+ * unspecified encoding, followed by a single zero byte.
+ *
+ * The escaping method consists of replacing all non-alphanumeric
+ * characters (see g_ascii_isalnum()) with their hexadecimal value
+ * preceded by an underscore (`_`). For example:
+ * `foo.bar.baz` will become `foo_2ebar_2ebaz`.
+ *
+ * This method is appropriate to use when the input is nearly
+ * a valid object path component but is not when your input
+ * is far from being a valid object path component.
+ * Other escaping algorithms are also valid to use with
+ * D-Bus object paths.
+ *
+ * This can be reversed with g_dbus_unescape_object_path().
+ *
+ * Returns: an escaped version of @bytes. Free with g_free().
+ * Since: 2.68
+ */
+
+
 /**
  * g_dbus_generate_guid:
  *
@@ -19536,6 +19605,26 @@
  */
 
 
+/**
+ * g_dbus_unescape_object_path:
+ * @s: the string to unescape
+ *
+ * Unescapes an string that was previously escaped with
+ * g_dbus_escape_object_path(). If the string is in a format that could
+ * not have been returned by g_dbus_escape_object_path(), this function
+ * returns %NULL.
+ *
+ * Encoding alphanumeric characters which do not need to be
+ * encoded is not allowed (e.g `_63` is not valid, the string
+ * should contain `c` instead).
+ *
+ * Returns: (array zero-terminated=1) (element-type guint8) (nullable): an
+ *   unescaped version of @s, or %NULL if @s is not a string returned
+ *   from g_dbus_escape_object_path(). Free with g_free().
+ * Since: 2.68
+ */
+
+
 /**
  * g_desktop_app_info_get_action_name:
  * @info: a #GDesktopAppInfo
@@ -22150,7 +22239,7 @@
 
 
 /**
- * g_file_get_basename:
+ * g_file_get_basename: (virtual get_basename)
  * @file: input #GFile
  *
  * Gets the base name (the last component of the path) for a given #GFile.
@@ -22254,7 +22343,7 @@
 
 
 /**
- * g_file_get_path:
+ * g_file_get_path: (virtual get_path)
  * @file: input #GFile
  *
  * Gets the local pathname for #GFile, if one exists. If non-%NULL, this is
@@ -22269,7 +22358,7 @@
 
 
 /**
- * g_file_get_relative_path:
+ * g_file_get_relative_path: (virtual get_relative_path)
  * @parent: input #GFile
  * @descendant: input #GFile
  *
@@ -22292,7 +22381,8 @@
  *
  * This call does no blocking I/O.
  *
- * Returns: a string containing the #GFile's URI.
+ * Returns: a string containing the #GFile's URI. If the #GFile was constructed
+ *     with an invalid URI, an invalid URI is returned.
  *     The returned string should be freed with g_free()
  *     when no longer needed.
  */
@@ -22309,11 +22399,14 @@
  * ]|
  * Common schemes include "file", "http", "ftp", etc.
  *
+ * The scheme can be different from the one used to construct the #GFile,
+ * in that it might be replaced with one that is logically equivalent to the #GFile.
+ *
  * This call does no blocking I/O.
  *
- * Returns: a string containing the URI scheme for the given
- *     #GFile. The returned string should be freed with g_free()
- *     when no longer needed.
+ * Returns: (nullable): a string containing the URI scheme for the given
+ *     #GFile or %NULL if the #GFile was constructed with an invalid URI. The
+ *     returned string should be freed with g_free() when no longer needed.
  */
 
 
@@ -36772,6 +36865,11 @@
  * notified of a %G_IO_OUT condition. (On Windows in particular, this is
  * very common due to the way the underlying APIs work.)
  *
+ * The sum of the sizes of each #GOutputVector in vectors must not be
+ * greater than %G_MAXSSIZE. If the message can be larger than this,
+ * then it is mandatory to use the g_socket_send_message_with_timeout()
+ * function.
+ *
  * On error -1 is returned and @error is set accordingly.
  *
  * Returns: Number of bytes written (which may be less than @size), or -1
@@ -42377,6 +42475,34 @@
  */
 
 
+/**
+ * g_win32_file_sync_stream_new:
+ * @handle: a Win32 HANDLE for a file.
+ * @owns_handle: %TRUE if newly-created stream owns the handle
+ *               (and closes it when destroyed)
+ * @stgm_mode: a combination of [STGM 
constants](https://docs.microsoft.com/en-us/windows/win32/stg/stgm-constants)
+ *             that specify the mode with which the stream
+ *             is opened.
+ * @output_hresult: (out) (optional): a HRESULT from the internal COM calls.
+ *                                    Will be `S_OK` on success.
+ *
+ * Creates an IStream object backed by a HANDLE.
+ *
+ * @stgm_mode should match the mode of the @handle, otherwise the stream might
+ * attempt to perform operations that the @handle does not allow. The implementation
+ * itself ignores these flags completely, they are only used to report
+ * the mode of the stream to third parties.
+ *
+ * The stream only does synchronous access and will never return `E_PENDING` on I/O.
+ *
+ * The returned stream object should be treated just like any other
+ * COM object, and released via `IUnknown_Release()`.
+ * its elements have been unreffed with g_object_unref().
+ *
+ * Returns: (nullable) (transfer full): a new IStream object on success, %NULL on failure.
+ */
+
+
 /**
  * g_win32_input_stream_get_close_handle:
  * @stream: a #GWin32InputStream
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index f7e7fc38..6d643089 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -5884,14 +5884,14 @@
  * - Do not report programming errors via #GError.
  *
  * - The last argument of a function that returns an error should
- *   be a location where a #GError can be placed (i.e. "#GError** error").
- *   If #GError is used with varargs, the #GError** should be the last
- *   argument before the "...".
+ *   be a location where a #GError can be placed (i.e. `GError **error`).
+ *   If #GError is used with varargs, the `GError**` should be the last
+ *   argument before the `...`.
  *
- * - The caller may pass %NULL for the #GError** if they are not interested
+ * - The caller may pass %NULL for the `GError**` if they are not interested
  *   in details of the exact error that occurred.
  *
- * - If %NULL is passed for the #GError** argument, then errors should
+ * - If %NULL is passed for the `GError**` argument, then errors should
  *   not be returned to the caller, but your function should still
  *   abort and return if an error occurs. That is, control flow should
  *   not be affected by whether the caller wants to get a #GError.
@@ -5905,11 +5905,13 @@
  * - If a #GError is reported, out parameters are not guaranteed to
  *   be set to any defined value.
  *
- * - A #GError* must be initialized to %NULL before passing its address
+ * - A `GError*` must be initialized to %NULL before passing its address
  *   to a function that can report errors.
  *
+ * - #GError structs must not be stack-allocated.
+ *
  * - "Piling up" errors is always a bug. That is, if you assign a
- *   new #GError to a #GError* that is non-%NULL, thus overwriting
+ *   new #GError to a `GError*` that is non-%NULL, thus overwriting
  *   the previous error, it indicates that you should have aborted
  *   the operation instead of continuing. If you were able to continue,
  *   you should have cleared the previous error with g_clear_error().
@@ -5917,12 +5919,12 @@
  *
  * - By convention, if you return a boolean value indicating success
  *   then %TRUE means success and %FALSE means failure. Avoid creating
- *   functions which have a boolean return value and a GError parameter,
+ *   functions which have a boolean return value and a #GError parameter,
  *   but where the boolean does something other than signal whether the
- *   GError is set.  Among other problems, it requires C callers to allocate
- *   a temporary error.  Instead, provide a "gboolean *" out parameter.
+ *   #GError is set.  Among other problems, it requires C callers to allocate
+ *   a temporary error.  Instead, provide a `gboolean *` out parameter.
  *   There are functions in GLib itself such as g_key_file_has_key() that
- *   are deprecated because of this. If %FALSE is returned, the error must
+ *   are hard to use because of this. If %FALSE is returned, the error must
  *   be set to a non-%NULL value.  One exception to this is that in situations
  *   that are already considered to be undefined behaviour (such as when a
  *   g_return_val_if_fail() check fails), the error need not be set.
@@ -5940,6 +5942,121 @@
  *   to add a check at the top of your function that the error return
  *   location is either %NULL or contains a %NULL error (e.g.
  *   `g_return_if_fail (error == NULL || *error == NULL);`).
+ *
+ * ## Extended #GError Domains # {#gerror-extended-domains}
+ *
+ * Since GLib 2.68 it is possible to extend the #GError type. This is
+ * done with the G_DEFINE_EXTENDED_ERROR() macro. To create an
+ * extended #GError type do something like this in the header file:
+ * |[<!-- language="C" -->
+ * typedef enum
+ * {
+ *   MY_ERROR_BAD_REQUEST,
+ * } MyError;
+ * #define MY_ERROR (my_error_quark ())
+ * GQuark my_error_quark (void);
+ * int
+ * my_error_get_parse_error_id (GError *error);
+ * const char *
+ * my_error_get_bad_request_details (GError *error);
+ * ]|
+ * and in implementation:
+ * |[<!-- language="C" -->
+ * typedef struct
+ * {
+ *   int parse_error_id;
+ *   char *bad_request_details;
+ * } MyErrorPrivate;
+ *
+ * static void
+ * my_error_private_init (MyErrorPrivate *priv)
+ * {
+ *   priv->parse_error_id = -1;
+ *   // No need to set priv->bad_request_details to NULL,
+ *   // the struct is initialized with zeros.
+ * }
+ *
+ * static void
+ * my_error_private_copy (const MyErrorPrivate *src_priv, MyErrorPrivate *dest_priv)
+ * {
+ *   dest_priv->parse_error_id = src_priv->parse_error_id;
+ *   dest_priv->bad_request_details = g_strdup (src_priv->bad_request_details);
+ * }
+ *
+ * static void
+ * my_error_private_clear (MyErrorPrivate *priv)
+ * {
+ *   g_free (priv->bad_request_details);
+ * }
+ *
+ * // This defines the my_error_get_private and my_error_quark functions.
+ * G_DEFINE_EXTENDED_ERROR (MyError, my_error)
+ *
+ * int
+ * my_error_get_parse_error_id (GError *error)
+ * {
+ *   MyErrorPrivate *priv = my_error_get_private (error);
+ *   g_return_val_if_fail (priv != NULL, -1);
+ *   return priv->parse_error_id;
+ * }
+ *
+ * const char *
+ * my_error_get_bad_request_details (GError *error)
+ * {
+ *   MyErrorPrivate *priv = my_error_get_private (error);
+ *   g_return_val_if_fail (priv != NULL, NULL);
+ *   g_return_val_if_fail (error->code != MY_ERROR_BAD_REQUEST, NULL);
+ *   return priv->bad_request_details;
+ * }
+ *
+ * static void
+ * my_error_set_bad_request (GError     **error,
+ *                           const char  *reason,
+ *                           int          error_id,
+ *                           const char  *details)
+ * {
+ *   MyErrorPrivate *priv;
+ *   g_set_error (error, MY_ERROR, MY_ERROR_BAD_REQUEST, "Invalid request: %s", reason);
+ *   if (error != NULL && *error != NULL)
+ *     {
+ *       priv = my_error_get_private (error);
+ *       g_return_val_if_fail (priv != NULL, NULL);
+ *       priv->parse_error_id = error_id;
+ *       priv->bad_request_details = g_strdup (details);
+ *     }
+ * }
+ * ]|
+ * An example of use of the error could be:
+ * |[<!-- language="C" -->
+ * gboolean
+ * send_request (GBytes *request, GError **error)
+ * {
+ *   ParseFailedStatus *failure = validate_request (request);
+ *   if (failure != NULL)
+ *     {
+ *       my_error_set_bad_request (error, failure->reason, failure->error_id, failure->details);
+ *       parse_failed_status_free (failure);
+ *       return FALSE;
+ *     }
+ *
+ *   return send_one (request, error);
+ * }
+ * ]|
+ *
+ * Please note that if you are a library author and your library
+ * exposes an existing error domain, then you can't make this error
+ * domain an extended one without breaking ABI. This is because
+ * earlier it was possible to create an error with this error domain
+ * on the stack and then copy it with g_error_copy(). If the new
+ * version of your library makes the error domain an extended one,
+ * then g_error_copy() called by code that allocated the error on the
+ * stack will try to copy more data than it used to, which will lead
+ * to undefined behavior. You must not stack-allocate errors with an
+ * extended error domain, and it is bad practice to stack-allocate any
+ * other #GErrors.
+ *
+ * Extended error domains in unloadable plugins/modules are not
+ * supported.
  */
 
 
@@ -16592,6 +16709,54 @@
  */
 
 
+/**
+ * g_error_domain_register:
+ * @error_type_name: string to create a #GQuark from
+ * @error_type_private_size: size of the private error data in bytes
+ * @error_type_init: function initializing fields of the private error data
+ * @error_type_copy: function copying fields of the private error data
+ * @error_type_clear: function freeing fields of the private error data
+ *
+ * This function registers an extended #GError domain.
+ * @error_type_name will be duplicated. Otherwise does the same as
+ * g_error_domain_register_static().
+ *
+ * Returns: #GQuark representing the error domain
+ * Since: 2.68
+ */
+
+
+/**
+ * g_error_domain_register_static:
+ * @error_type_name: static string to create a #GQuark from
+ * @error_type_private_size: size of the private error data in bytes
+ * @error_type_init: function initializing fields of the private error data
+ * @error_type_copy: function copying fields of the private error data
+ * @error_type_clear: function freeing fields of the private error data
+ *
+ * This function registers an extended #GError domain.
+ *
+ * @error_type_name should not be freed. @error_type_private_size must
+ * be greater than 0.
+ *
+ * @error_type_init receives an initialized #GError and should then initialize
+ * the private data.
+ *
+ * @error_type_copy is a function that receives both original and a copy
+ * #GError and should copy the fields of the private error data. The standard
+ * #GError fields are already handled.
+ *
+ * @error_type_clear receives the pointer to the error, and it should free the
+ * fields of the private error data. It should not free the struct itself though.
+ *
+ * Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it
+ * already takes care of passing valid information to this function.
+ *
+ * Returns: #GQuark representing the error domain
+ * Since: 2.68
+ */
+
+
 /**
  * g_error_free:
  * @error: a #GError
@@ -17648,6 +17813,9 @@
  * CSIDL_COMMON_APPDATA folder. This information will not roam and is available
  * to anyone using the computer.
  *
+ * The return value is cached and modifying it at runtime is not supported, as
+ * it’s not thread-safe to modify environment variables at runtime.
+ *
  * Returns: (array zero-terminated=1) (element-type filename) (transfer none):
  *     a %NULL-terminated array of strings owned by GLib that must not be
  *     modified or freed.
@@ -17690,6 +17858,9 @@
  * Note that on Windows the returned list can vary depending on where
  * this function is called.
  *
+ * The return value is cached and modifying it at runtime is not supported, as
+ * it’s not thread-safe to modify environment variables at runtime.
+ *
  * Returns: (array zero-terminated=1) (element-type filename) (transfer none):
  *     a %NULL-terminated array of strings owned by GLib that must not be
  *     modified or freed.
@@ -17736,6 +17907,9 @@
  * `C:\Documents and Settings\username\Local Settings\Temporary Internet Files`.
  * See the [documentation for 
`CSIDL_INTERNET_CACHE`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_internet_cache).
  *
+ * The return value is cached and modifying it at runtime is not supported, as
+ * it’s not thread-safe to modify environment variables at runtime.
+ *
  * Returns: (type filename) (transfer none): a string owned by GLib that
  *   must not be modified or freed.
  * Since: 2.6
@@ -17760,6 +17934,9 @@
  * Note that in this case on Windows it will be  the same
  * as what g_get_user_data_dir() returns.
  *
+ * The return value is cached and modifying it at runtime is not supported, as
+ * it’s not thread-safe to modify environment variables at runtime.
+ *
  * Returns: (type filename) (transfer none): a string owned by GLib that
  *   must not be modified or freed.
  * Since: 2.6
@@ -17784,6 +17961,9 @@
  * Note that in this case on Windows it will be the same
  * as what g_get_user_config_dir() returns.
  *
+ * The return value is cached and modifying it at runtime is not supported, as
+ * it’s not thread-safe to modify environment variables at runtime.
+ *
  * Returns: (type filename) (transfer none): a string owned by GLib that must
  *   not be modified or freed.
  * Since: 2.6
@@ -17816,6 +17996,9 @@
  * In the case that this variable is not set, we return the value of
  * g_get_user_cache_dir(), after verifying that it exists.
  *
+ * The return value is cached and modifying it at runtime is not supported, as
+ * it’s not thread-safe to modify environment variables at runtime.
+ *
  * Returns: (type filename): a string owned by GLib that must not be
  *     modified or freed.
  * Since: 2.28
@@ -30188,10 +30371,10 @@
  * {
  *   SomeWidget *self = data;
  *    
- *   GDK_THREADS_ENTER ();
+ *   g_mutex_lock (&self->idle_id_mutex);
  *   // do stuff with self
  *   self->idle_id = 0;
- *   GDK_THREADS_LEAVE ();
+ *   g_mutex_unlock (&self->idle_id_mutex);
  *    
  *   return G_SOURCE_REMOVE;
  * }
@@ -30199,10 +30382,20 @@
  * static void
  * some_widget_do_stuff_later (SomeWidget *self)
  * {
+ *   g_mutex_lock (&self->idle_id_mutex);
  *   self->idle_id = g_idle_add (idle_callback, self);
+ *   g_mutex_unlock (&self->idle_id_mutex);
  * }
  *  
  * static void
+ * some_widget_init (SomeWidget *self)
+ * {
+ *   g_mutex_init (&self->idle_id_mutex);
+ *
+ *   // ...
+ * }
+ *
+ * static void
  * some_widget_finalize (GObject *object)
  * {
  *   SomeWidget *self = SOME_WIDGET (object);
@@ -30210,6 +30403,8 @@
  *   if (self->idle_id)
  *     g_source_remove (self->idle_id);
  *    
+ *   g_mutex_clear (&self->idle_id_mutex);
+ *
  *   G_OBJECT_CLASS (parent_class)->finalize (object);
  * }
  * ]|
@@ -30226,12 +30421,12 @@
  * {
  *   SomeWidget *self = data;
  *   
- *   GDK_THREADS_ENTER ();
+ *   g_mutex_lock (&self->idle_id_mutex);
  *   if (!g_source_is_destroyed (g_main_current_source ()))
  *     {
  *       // do stuff with self
  *     }
- *   GDK_THREADS_LEAVE ();
+ *   g_mutex_unlock (&self->idle_id_mutex);
  *   
  *   return FALSE;
  * }
@@ -32962,6 +33157,21 @@
  */
 
 
+/**
+ * g_test_get_path:
+ *
+ * Gets the test path for the test currently being run.
+ *
+ * In essence, it will be the same string passed as the first argument to
+ * e.g. g_test_add() when the test was added.
+ *
+ * This function returns a valid string only within a test function.
+ *
+ * Returns: the test path for the test currently being run
+ * Since: 2.68
+ */
+
+
 /**
  * g_test_get_root:
  *
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index fd454260..703c20e1 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -1830,7 +1830,7 @@
  * associated with a #GObject, and want the callback to no longer run
  * after the object is is freed.
  *
- * Returns: a new #GCClosure
+ * Returns: (transfer floating): a new #GCClosure
  */
 
 
@@ -1845,7 +1845,7 @@
  * associated with a #GObject, and want the callback to no longer run
  * after the object is is freed.
  *
- * Returns: a new #GCClosure
+ * Returns: (transfer floating): a new #GCClosure
  */
 
 
@@ -1994,7 +1994,7 @@
  * @object and the created closure. This function is mainly useful
  * when implementing new types of closures.
  *
- * Returns: (transfer full): a newly allocated #GClosure
+ * Returns: (transfer floating): a newly allocated #GClosure
  */
 
 
@@ -3858,7 +3858,8 @@
  * @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): (transfer full): a newly allocated #GParamSpec instance
+ * Returns: (type GObject.ParamSpec): (transfer floating): a newly allocated
+ *     #GParamSpec instance, which is initially floating
  */
 
 
@@ -4420,8 +4421,8 @@
  * @signal_id: the signal identifier, as returned by g_signal_lookup().
  * @detail: the detail on which to call the hook.
  * @hook_func: (not nullable): a #GSignalEmissionHook function.
- * @hook_data: (nullable): user data for @hook_func.
- * @data_destroy: (nullable): a #GDestroyNotify for @hook_data.
+ * @hook_data: (nullable) (closure hook_func): user data for @hook_func.
+ * @data_destroy: (nullable) (destroy hook_data): 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
@@ -4496,8 +4497,8 @@
  * @instance: (type GObject.Object): the instance to connect to.
  * @detailed_signal: a string of the form "signal-name::detail".
  * @c_handler: (not nullable): the #GCallback to connect.
- * @data: (nullable): data to pass to @c_handler calls.
- * @destroy_data: (nullable): a #GClosureNotify for @data.
+ * @data: (nullable) (closure c_handler): data to pass to @c_handler calls.
+ * @destroy_data: (nullable) (destroy data): a #GClosureNotify for @data.
  * @connect_flags: a combination of #GConnectFlags.
  *
  * Connects a #GCallback function to a signal for a particular object. Similar
@@ -4648,7 +4649,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: (nullable): The closure data of the handler's closure.
+ * @data: (nullable) (closure closure): 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
@@ -4701,7 +4702,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: (nullable): The closure data of the handlers' closures.
+ * @data: (nullable) (closure closure): 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
@@ -4734,7 +4735,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: (nullable): The closure data of the handlers' closures.
+ * @data: (nullable) (closure closure): 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
@@ -4758,7 +4759,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: (nullable): The closure data of the handlers' closures.
+ * @data: (nullable) (closure closure): 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
@@ -4876,7 +4877,7 @@
  *  for this type. Used to invoke a class method generically. Pass 0 to
  *  not associate a class method slot with this signal.
  * @accumulator: (nullable): the accumulator for this signal; may be %NULL.
- * @accu_data: (nullable): user data for the @accumulator.
+ * @accu_data: (nullable) (closure accumulator): 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
@@ -4925,7 +4926,7 @@
  *  this signal. Used to invoke a class method generically. Pass %NULL to
  *  not associate a class method with this signal.
  * @accumulator: (nullable): the accumulator for this signal; may be %NULL.
- * @accu_data: (nullable): user data for the @accumulator.
+ * @accu_data: (nullable) (closure accumulator): 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
@@ -4965,7 +4966,7 @@
  *  %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
  * @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.
+ * @accu_data: (nullable) (closure accumulator): 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
@@ -4995,7 +4996,7 @@
  * @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
+ * @accu_data: (nullable) (closure accumulator): 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