gir: Update annotations from glib git master

3 files changed, 329 insertions, 332 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 947b71f6..4de9e6e2 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -353,6 +353,21 @@
 
 
 /**
+ * GApplication::name-lost:
+ * @application: the application
+ *
+ * The ::name-lost signal is emitted only on the registered primary instance
+ * when a new instance has taken over. This can only happen if the application
+ * is using the %G_APPLICATION_ALLOW_REPLACEMENT flag.
+ *
+ * The default handler for this signal calls g_application_quit().
+ *
+ * Returns: %TRUE if the signal has been handled
+ * Since: 2.60
+ */
+
+
+/**
  * GApplication::open:
  * @application: the application
  * @files: (array length=n_files) (element-type GFile): an array of #GFiles
@@ -429,10 +444,11 @@
  *     If this function returns %TRUE, registration will proceed; otherwise
  *     registration will abort. Since: 2.34
  * @dbus_unregister: invoked locally during unregistration, if the application
- *     is using its D-Bus backend. Use this to undo anything done by the
- *     @dbus_register vfunc. Since: 2.34
+ *     is using its D-Bus backend. Use this to undo anything done by
+ *     the @dbus_register vfunc. Since: 2.34
  * @handle_local_options: invoked locally after the parsing of the commandline
  *  options has occurred. Since: 2.40
+ * @name_lost: invoked when another instance is taking over the name. Since: 2.60
  *
  * Virtual function table for #GApplication.
  *
@@ -1707,6 +1723,9 @@
  * g_dtls_connection_set_rehandshake_mode().
  *
  * Since: 2.48
+ * Deprecated: 2.60.: Changing the rehandshake mode is no longer
+ *   required for compatibility. Also, rehandshaking has been removed
+ *   from the TLS protocol in TLS 1.3.
  */
 
 
@@ -2318,7 +2337,7 @@
  * GMountOperation:is-tcrypt-hidden-volume:
  *
  * Whether the device to be unlocked is a TCRYPT hidden volume.
- * See https://www.veracrypt.fr/en/Hidden%20Volume.html.
+ * See [the VeraCrypt documentation](https://www.veracrypt.fr/en/Hidden%20Volume.html).
  *
  * Since: 2.58
  */
@@ -2331,7 +2350,7 @@
  * In this context, a system volume is a volume with a bootloader
  * and operating system installed. This is only supported for Windows
  * operating systems. For further documentation, see
- * https://www.veracrypt.fr/en/System%20Encryption.html.
+ * [the VeraCrypt documentation](https://www.veracrypt.fr/en/System%20Encryption.html).
  *
  * Since: 2.58
  */
@@ -2356,7 +2375,7 @@
  * GMountOperation:pim:
  *
  * The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See
- * https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20(PIM).html.
+ * [the VeraCrypt documentation](https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20(PIM).html).
  *
  * Since: 2.58
  */
@@ -9553,10 +9572,10 @@
  * for credentials.
  *
  * The callback will be fired when the operation has resolved (either
- * with success or failure), and a #GAsyncReady structure will be
+ * with success or failure), and a #GAsyncResult instance will be
  * passed to the callback.  That callback should then call
  * g_volume_mount_finish() with the #GVolume instance and the
- * #GAsyncReady data to see if the operation was completed
+ * #GAsyncResult data to see if the operation was completed
  * successfully.  If an @error is present when g_volume_mount_finish()
  * is called, then it will be filled with any error information.
  *
@@ -10917,7 +10936,7 @@
  * @uri: the uri to show
  * @context: (nullable): an optional #GAppLaunchContext
  * @cancellable: (nullable): a #GCancellable
- * @callback: (nullable): a #GASyncReadyCallback to call when the request is done
+ * @callback: (nullable): a #GAsyncReadyCallback to call when the request is done
  * @user_data: (nullable): data to pass to @callback
  *
  * Async version of g_app_info_launch_default_for_uri().
@@ -13195,7 +13214,7 @@
  *
  * See also g_cancellable_make_pollfd().
  *
- * Returns: A valid file descriptor. %-1 if the file descriptor
+ * Returns: A valid file descriptor. `-1` if the file descriptor
  * is not supported, or on errors.
  */
 
@@ -13910,7 +13929,7 @@
  *
  * Reads an unsigned 8-bit/1-byte value from @stream.
  *
- * Returns: an unsigned 8-bit/1-byte value read from the @stream or %0
+ * Returns: an unsigned 8-bit/1-byte value read from the @stream or `0`
  * if an error occurred.
  */
 
@@ -13926,7 +13945,7 @@
  * In order to get the correct byte order for this read operation,
  * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
  *
- * Returns: a signed 16-bit/2-byte value read from @stream or %0 if
+ * Returns: a signed 16-bit/2-byte value read from @stream or `0` if
  * an error occurred.
  */
 
@@ -13946,7 +13965,7 @@
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
  *
- * Returns: a signed 32-bit/4-byte value read from the @stream or %0 if
+ * Returns: a signed 32-bit/4-byte value read from the @stream or `0` if
  * an error occurred.
  */
 
@@ -13966,7 +13985,7 @@
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
  *
- * Returns: a signed 64-bit/8-byte value read from @stream or %0 if
+ * Returns: a signed 64-bit/8-byte value read from @stream or `0` if
  * an error occurred.
  */
 
@@ -14091,7 +14110,7 @@
  * In order to get the correct byte order for this read operation,
  * see g_data_input_stream_get_byte_order() and g_data_input_stream_set_byte_order().
  *
- * Returns: an unsigned 16-bit/2-byte value read from the @stream or %0 if
+ * Returns: an unsigned 16-bit/2-byte value read from the @stream or `0` if
  * an error occurred.
  */
 
@@ -14111,7 +14130,7 @@
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
  *
- * Returns: an unsigned 32-bit/4-byte value read from the @stream or %0 if
+ * Returns: an unsigned 32-bit/4-byte value read from the @stream or `0` if
  * an error occurred.
  */
 
@@ -14131,7 +14150,7 @@
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
  *
- * Returns: an unsigned 64-bit/8-byte read from @stream or %0 if
+ * Returns: an unsigned 64-bit/8-byte read from @stream or `0` if
  * an error occurred.
  */
 
@@ -15466,7 +15485,7 @@
  * bus. This can also be used to figure out if @connection is a
  * message bus connection.
  *
- * Returns: the unique name or %NULL if @connection is not a message
+ * Returns: (nullable): the unique name or %NULL if @connection is not a message
  *     bus connection. Do not free this string, it is owned by
  *     @connection.
  * Since: 2.26
@@ -19236,7 +19255,7 @@
  * Returns: (array zero-terminated=1 length=length) (element-type utf8) (transfer full):
  *  a %NULL-terminated string array or %NULL if the specified
  *  key cannot be found. The array should be freed with g_strfreev().
- * Since: 2.59.0
+ * Since: 2.60.0
  */
 
 
@@ -20094,8 +20113,15 @@
  * Likewise, on the server side, although a handshake is necessary at
  * the beginning of the communication, you do not need to call this
  * function explicitly unless you want clearer error reporting.
- * However, you may call g_dtls_connection_handshake() later on to
- * renegotiate parameters (encryption methods, etc) with the client.
+ *
+ * If TLS 1.2 or older is in use, you may call
+ * g_dtls_connection_handshake() after the initial handshake to
+ * rehandshake; however, this usage is deprecated because rehandshaking
+ * is no longer part of the TLS protocol in TLS 1.3. Accordingly, the
+ * behavior of calling this function after the initial handshake is now
+ * undefined, except it is guaranteed to be reasonable and
+ * nondestructive so as to preserve compatibility with code written for
+ * older versions of GLib.
  *
  * #GDtlsConnection::accept_certificate may be emitted during the
  * handshake.
@@ -20224,6 +20250,9 @@
  * software.
  *
  * Since: 2.48
+ * Deprecated: 2.60.: Changing the rehandshake mode is no longer
+ *   required for compatibility. Also, rehandshaking has been removed
+ *   from the TLS protocol in TLS 1.3.
  */
 
 
@@ -38398,6 +38427,9 @@
  *
  * Returns: @conn's rehandshaking mode
  * Since: 2.28
+ * Deprecated: 2.60.: Changing the rehandshake mode is no longer
+ *   required for compatibility. Also, rehandshaking has been removed
+ *   from the TLS protocol in TLS 1.3.
  */
 
 
@@ -38450,11 +38482,15 @@
  * Likewise, on the server side, although a handshake is necessary at
  * the beginning of the communication, you do not need to call this
  * function explicitly unless you want clearer error reporting.
- * However, you may call g_tls_connection_handshake() later on to
- * rehandshake, if TLS 1.2 or older is in use. With TLS 1.3, the
- * behavior is undefined but guaranteed to be reasonable and
- * nondestructive, so most older code should be expected to continue to
- * work without changes.
+ *
+ * If TLS 1.2 or older is in use, you may call
+ * g_tls_connection_handshake() after the initial handshake to
+ * rehandshake; however, this usage is deprecated because rehandshaking
+ * is no longer part of the TLS protocol in TLS 1.3. Accordingly, the
+ * behavior of calling this function after the initial handshake is now
+ * undefined, except it is guaranteed to be reasonable and
+ * nondestructive so as to preserve compatibility with code written for
+ * older versions of GLib.
  *
  * #GTlsConnection::accept_certificate may be emitted during the
  * handshake.
@@ -38584,6 +38620,9 @@
  * software.
  *
  * Since: 2.28
+ * Deprecated: 2.60.: Changing the rehandshake mode is no longer
+ *   required for compatibility. Also, rehandshaking has been removed
+ *   from the TLS protocol in TLS 1.3.
  */
 
 
@@ -38735,7 +38774,7 @@
  *
  * Lookup the issuer of @certificate in the database.
  *
- * The %issuer property
+ * The #GTlsCertificate:issuer property
  * of @certificate is not modified, and the two certificates are not hooked
  * into a chain.
  *
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 8a8ce87a..43fc6ef7 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -9064,6 +9064,53 @@
 
 
 /**
+ * SECTION:warnings
+ * @title: Warnings and Assertions
+ * @short_description: warnings and assertions to use in runtime code
+ *
+ * GLib defines several warning functions and assertions which can be used to
+ * warn of programmer errors when calling functions, and print error messages
+ * from command line programs.
+ *
+ * The g_return_if_fail(), g_return_val_if_fail(), g_return_if_reached() and
+ * g_return_val_if_reached() macros are intended as pre-condition assertions, to
+ * be used at the top of a public function to check that the function’s
+ * arguments are acceptable. Any failure of such a pre-condition assertion is
+ * considered a programming error on the part of the caller of the public API,
+ * and the program is considered to be in an undefined state afterwards. They
+ * are similar to the libc assert() function, but provide more context on
+ * failures.
+ *
+ * For example:
+ * |[<!-- language="C" -->
+ * gboolean
+ * g_dtls_connection_shutdown (GDtlsConnection  *conn,
+ *                             gboolean          shutdown_read,
+ *                             gboolean          shutdown_write,
+ *                             GCancellable     *cancellable,
+ *                             GError          **error)
+ * {
+ *   // local variable declarations
+ *
+ *   g_return_val_if_fail (G_IS_DTLS_CONNECTION (conn), FALSE);
+ *   g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
+ *   g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
+ *
+ *   // function body
+ *
+ *   return return_val;
+ * }
+ * ]|
+ *
+ * g_print(), g_printerr() and g_set_print_handler() are intended to be used for
+ * output from command line applications, since they output to standard output
+ * and standard error by default — whereas functions like g_message() and
+ * g_log() may be redirected to special purpose message windows, files, or the
+ * system journal.
+ */
+
+
+/**
  * SECTION:windows
  * @title: Windows Compatibility Functions
  * @short_description: UNIX emulation on Windows
@@ -10281,11 +10328,14 @@
 
 /**
  * g_assertion_message_expr: (skip)
- * @domain: (nullable):
- * @file:
- * @line:
- * @func:
- * @expr: (nullable):
+ * @domain: (nullable): log domain
+ * @file: file containing the assertion
+ * @line: line number of the assertion
+ * @func: function containing the assertion
+ * @expr: (nullable): expression which failed
+ *
+ * Internal function used to print messages from the public g_assert() and
+ * g_assert_not_reached() macros.
  */
 
 
@@ -11224,7 +11274,7 @@
  * g_atomic_ref_count_init:
  * @arc: the address of an atomic reference count variable
  *
- * Atomically initializes a reference count variable.
+ * Initializes a reference count variable.
  *
  * Since: 2.58
  */
@@ -26947,9 +26997,12 @@
 
 /**
  * g_return_if_fail_warning: (skip)
- * @log_domain: (nullable):
- * @pretty_function:
- * @expression: (nullable):
+ * @log_domain: (nullable): log domain
+ * @pretty_function: function containing the assertion
+ * @expression: (nullable): expression which failed
+ *
+ * Internal function used to print messages from the public g_return_if_fail()
+ * and g_return_val_if_fail() macros.
  */
 
 
@@ -38906,11 +38959,14 @@
 
 /**
  * g_warn_message: (skip)
- * @domain: (nullable):
- * @file:
- * @line:
- * @func:
- * @warnexpr: (nullable):
+ * @domain: (nullable): log domain
+ * @file: file containing the warning
+ * @line: line number of the warning
+ * @func: function containing the warning
+ * @warnexpr: (nullable): expression which failed
+ *
+ * Internal function used to print messages from the public g_warn_if_reached()
+ * and g_warn_if_fail() macros.
  */
 
 
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index b6c3f152..079a6248 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -910,22 +910,17 @@
 
 /**
  * g_cclosure_marshal_BOOLEAN__FLAGS:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: a #GValue which can store the returned #gboolean
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding instance and arg1
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with handlers that
- * take a flags type as an argument and return a boolean.  If you have
- * such a signal, you will probably also need to use an accumulator,
- * such as g_signal_accumulator_true_handled().
+ * A marshaller for a #GCClosure with a callback of type
+ * `gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter
+ * denotes a flags type.
  */
 
 
@@ -985,39 +980,23 @@
 
 /**
  * g_cclosure_marshal_BOOL__FLAGS:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
  *
- * An old alias for g_cclosure_marshal_BOOLEAN__FLAGS().
+ * Another name for g_cclosure_marshal_BOOLEAN__FLAGS().
  */
 
 
 /**
  * g_cclosure_marshal_STRING__OBJECT_POINTER:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: a #GValue, which can store the returned string
+ * @n_param_values: 3
+ * @param_values: a #GValue array holding instance, arg1 and arg2
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with handlers that
- * take a #GObject and a pointer and produce a string.  It is highly
- * unlikely that your signal handler fits this description.
+ * A marshaller for a #GCClosure with a callback of type
+ * `gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`.
  */
 
 
@@ -1042,20 +1021,16 @@
 
 /**
  * g_cclosure_marshal_VOID__BOOLEAN:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the #gboolean parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with a single
- * boolean argument.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`.
  */
 
 
@@ -1080,20 +1055,16 @@
 
 /**
  * g_cclosure_marshal_VOID__BOXED:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the #GBoxed* parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with a single
- * argument which is any boxed pointer type.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`.
  */
 
 
@@ -1118,20 +1089,16 @@
 
 /**
  * g_cclosure_marshal_VOID__CHAR:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the #gchar parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with a single
- * character argument.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`.
  */
 
 
@@ -1156,20 +1123,16 @@
 
 /**
  * g_cclosure_marshal_VOID__DOUBLE:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the #gdouble parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with one
- * double-precision floating point argument.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`.
  */
 
 
@@ -1194,20 +1157,16 @@
 
 /**
  * g_cclosure_marshal_VOID__ENUM:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the enumeration parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with a single
- * argument with an enumerated type.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type..
  */
 
 
@@ -1232,20 +1191,16 @@
 
 /**
  * g_cclosure_marshal_VOID__FLAGS:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the flags parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with a single
- * argument with a flags types.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type.
  */
 
 
@@ -1270,20 +1225,16 @@
 
 /**
  * g_cclosure_marshal_VOID__FLOAT:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the #gfloat parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with one
- * single-precision floating point argument.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`.
  */
 
 
@@ -1308,20 +1259,16 @@
 
 /**
  * g_cclosure_marshal_VOID__INT:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the #gint parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with a single
- * integer argument.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)`.
  */
 
 
@@ -1346,20 +1293,16 @@
 
 /**
  * g_cclosure_marshal_VOID__LONG:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the #glong parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with with a single
- * long integer argument.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, glong arg1, gpointer user_data)`.
  */
 
 
@@ -1384,20 +1327,16 @@
 
 /**
  * g_cclosure_marshal_VOID__OBJECT:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the #GObject* parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with a single
- * #GObject argument.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`.
  */
 
 
@@ -1422,20 +1361,16 @@
 
 /**
  * g_cclosure_marshal_VOID__PARAM:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the #GParamSpec* parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with a single
- * argument of type #GParamSpec.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`.
  */
 
 
@@ -1460,24 +1395,16 @@
 
 /**
  * g_cclosure_marshal_VOID__POINTER:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
- *
- * A #GClosureMarshal function for use with signals with a single raw
- * pointer argument type.
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the #gpointer parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * If it is possible, it is better to use one of the more specific
- * functions such as g_cclosure_marshal_VOID__OBJECT() or
- * g_cclosure_marshal_VOID__OBJECT().
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`.
  */
 
 
@@ -1502,20 +1429,16 @@
 
 /**
  * g_cclosure_marshal_VOID__STRING:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the #gchar* parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with a single string
- * argument.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`.
  */
 
 
@@ -1540,20 +1463,16 @@
 
 /**
  * g_cclosure_marshal_VOID__UCHAR:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the #guchar parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with a single
- * unsigned character argument.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`.
  */
 
 
@@ -1578,39 +1497,31 @@
 
 /**
  * g_cclosure_marshal_VOID__UINT:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the #guint parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with with a single
- * unsigned integer argument.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, guint arg1, gpointer user_data)`.
  */
 
 
 /**
  * g_cclosure_marshal_VOID__UINT_POINTER:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 3
+ * @param_values: a #GValue array holding instance, arg1 and arg2
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with a unsigned int
- * and a pointer as arguments.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`.
  */
 
 
@@ -1654,20 +1565,16 @@
 
 /**
  * g_cclosure_marshal_VOID__ULONG:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the #gulong parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with a single
- * unsigned long integer argument.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`.
  */
 
 
@@ -1692,20 +1599,18 @@
 
 /**
  * g_cclosure_marshal_VOID__VARIANT:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 2
+ * @param_values: a #GValue array holding the instance and the #GVariant* parameter
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with a single
- * #GVariant argument.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`.
+ *
+ * Since: 2.26
  */
 
 
@@ -1730,19 +1635,16 @@
 
 /**
  * g_cclosure_marshal_VOID__VOID:
- * @closure: A #GClosure.
- * @return_value: A #GValue to store the return value. May be %NULL
- *   if the callback of closure doesn't return a value.
- * @n_param_values: The length of the @param_values array.
- * @param_values: An array of #GValues holding the arguments
- *   on which to invoke the callback of closure.
- * @invocation_hint: The invocation hint given as the last argument to
- *   g_closure_invoke().
- * @marshal_data: Additional data specified when registering the
- *   marshaller, see g_closure_set_marshal() and
- *   g_closure_set_meta_marshal()
+ * @closure: the #GClosure to which the marshaller belongs
+ * @return_value: ignored
+ * @n_param_values: 1
+ * @param_values: a #GValue array holding only the instance
+ * @invocation_hint: the invocation hint given as the last argument
+ *  to g_closure_invoke()
+ * @marshal_data: additional data specified when registering the marshaller
  *
- * A #GClosureMarshal function for use with signals with no arguments.
+ * A marshaller for a #GCClosure with a callback of type
+ * `void (*callback) (gpointer instance, gpointer user_data)`.
  */
 
 
@@ -6513,7 +6415,7 @@
  *
  * Get the contents of a variant #GValue.
  *
- * Returns: (nullable): variant contents of @value (may be %NULL)
+ * Returns: (transfer none) (nullable): variant contents of @value (may be %NULL)
  * Since: 2.26
  */