[gobject-introspection] Update the GLib introspection data

[Emmanuele Bassi <ebassi src gnome org>]

commit 530d73602fd8363f2d3513100fc67e2d6e56db5c
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Fri Aug 21 14:21:42 2015 +0100

    Update the GLib introspection data
    
    Against GLib 2.45.6.

 gir/gio-2.0.c     |   86 ++++++++--
 gir/glib-2.0.c    |  150 +++++++++++----
 gir/gobject-2.0.c |  524 +++++++++++++++++++++++------------------------------
 3 files changed, 413 insertions(+), 347 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 4d98f21..3e4e088 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -316,8 +316,8 @@
  *
  * In the event that the application is marked
  * %G_APPLICATION_HANDLES_COMMAND_LINE the "normal processing" will
- * send the @option dictionary to the primary instance where it can be
- * read with g_application_command_line_get_options().  The signal
+ * send the @options dictionary to the primary instance where it can be
+ * read with g_application_command_line_get_options_dict().  The signal
  * handler can modify the dictionary before returning, and the
  * modified dictionary will be sent.
  *
@@ -2176,6 +2176,31 @@
 
 
 /**
+ * GNetworkMonitor:network-metered:
+ *
+ * Whether the network is considered metered. That is, whether the
+ * system has traffic flowing through the default connection that is
+ * subject to limitations set by service providers. For example, traffic
+ * might be billed by the amount of data transmitted, or there might be a
+ * quota on the amount of traffic per month. This is typical with tethered
+ * connections (3G and 4G) and in such situations, bandwidth intensive
+ * applications may wish to avoid network activity where possible if it will
+ * cost the user money or use up their limited quota.
+ *
+ * If more information is required about specific devices then the
+ * system network management API should be used instead (for example,
+ * NetworkManager or ConnMan).
+ *
+ * If this information is not available then no networks will be
+ * marked as metered.
+ *
+ * See also #GNetworkMonitor:network-available.
+ *
+ * Since: 2.46
+ */
+
+
+/**
  * GNetworkMonitorInterface:
  * @g_iface: The parent interface.
  * @network_changed: the virtual function pointer for the
@@ -10876,6 +10901,16 @@
 
 
 /**
+ * _g_poll_file_monitor_new:
+ * @file: a #GFile.
+ *
+ * Polls @file for changes.
+ *
+ * Returns: a new #GFileMonitor for the given #GFile.
+ */
+
+
+/**
  * g_action_activate:
  * @action: a #GAction
  * @parameter: (allow-none): the parameter to the activation
@@ -16188,6 +16223,25 @@
 
 
 /**
+ * g_dbus_connection_register_object_with_closures: (rename-to g_dbus_connection_register_object)
+ * @connection: A #GDBusConnection.
+ * @object_path: The object path to register at.
+ * @interface_info: Introspection data for the interface.
+ * @method_call_closure: (nullable): #GClosure for handling incoming method calls.
+ * @get_property_closure: (nullable): #GClosure for getting a property.
+ * @set_property_closure: (nullable): #GClosure for setting a property.
+ * @error: Return location for error or %NULL.
+ *
+ * Version of g_dbus_connection_register_object() using closures instead of a
+ * #GDBusInterfaceVTable for easier binding in other languages.
+ *
+ * Returns: 0 if @error is set, otherwise a registration id (never 0)
+ * that can be used with g_dbus_connection_unregister_object() .
+ * Since: 2.46
+ */
+
+
+/**
  * g_dbus_connection_register_subtree:
  * @connection: a #GDBusConnection
  * @object_path: the object path to register the subtree at
@@ -16435,7 +16489,8 @@
  *     all object paths
  * @arg0: (allow-none): contents of first string argument to match on or %NULL
  *     to match on all kinds of arguments
- * @flags: flags describing how to subscribe to the signal (currently unused)
+ * @flags: #GDBusSignalFlags describing how arg0 is used in subscribing to the
+ *     signal
  * @callback: callback to invoke when there is a signal matching the requested data
  * @user_data: user data to pass to @callback
  * @user_data_free_func: (allow-none): function to free @user_data with when
@@ -28459,6 +28514,18 @@
 
 
 /**
+ * g_network_monitor_get_network_metered:
+ * @monitor: the #GNetworkMonitor
+ *
+ * Checks if the network is metered.
+ * See #GNetworkMonitor:network-metered for more details.
+ *
+ * Returns: whether the connection is metered
+ * Since: 2.46
+ */
+
+
+/**
  * g_network_service_get_domain:
  * @srv: a #GNetworkService
  *
@@ -29457,16 +29524,6 @@
 
 
 /**
- * g_poll_file_monitor_new:
- * @file: a #GFile.
- *
- * Polls @file for changes.
- *
- * Returns: a new #GFileMonitor for the given #GFile.
- */
-
-
-/**
  * g_pollable_input_stream_can_poll:
  * @stream: a #GPollableInputStream.
  *
@@ -30441,6 +30498,9 @@
  * The return result is a %NULL terminated list of strings which should
  * be released with g_strfreev().
  *
+ * If @path is invalid or does not exist in the #GResource,
+ * %G_RESOURCE_ERROR_NOT_FOUND will be returned.
+ *
  * @lookup_flags controls the behaviour of the lookup.
  *
  * Returns: (array zero-terminated=1) (transfer full): an array of constant strings
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index c5d8675..c5a947e 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -6956,6 +6956,35 @@
  * On UNIX, the GLib mainloop is incompatible with fork(). Any program
  * using the mainloop must either exec() or exit() from the child
  * without returning to the mainloop.
+ *
+ * ## Memory management of sources # {#mainloop-memory-management}
+ *
+ * There are two options for memory management of the user data passed to a
+ * #GSource to be passed to its callback on invocation. This data is provided
+ * in calls to g_timeout_add(), g_timeout_add_full(), g_idle_add(), etc. and
+ * more generally, using g_source_set_callback(). This data is typically an
+ * object which ‘owns’ the timeout or idle callback, such as a widget or a
+ * network protocol implementation. In many cases, it is an error for the
+ * callback to be invoked after this owning object has been destroyed, as that
+ * results in use of freed memory.
+ *
+ * The first, and preferred, option is to store the source ID returned by
+ * functions such as g_timeout_add() or g_source_attach(), and explicitly
+ * remove that source from the main context using g_source_remove() when the
+ * owning object is finalised. This ensures that the callback can only be
+ * invoked while the object is still alive.
+ *
+ * The second option is to hold a strong reference to the object in the
+ * callback, and to release it in the callback’s #GDestroyNotify. This ensures
+ * that the object is kept alive until after the source is finalized, which is
+ * guaranteed to be after it is invoked for the final time. The #GDestroyNotify
+ * is another callback passed to the ‘full’ variants of #GSource functions (for
+ * example, g_timeout_add_full()). It is called when the source is finalized,
+ * and is designed for releasing references like this.
+ *
+ * One important caveat of this second approach is that it will keep the object
+ * alive indefinitely if the main loop is stopped before the #GSource is
+ * invoked, which may be undesirable.
  */
 
 
@@ -7023,7 +7052,7 @@
  * g_slice_free(), plain malloc() with free(), and (if you're using C++)
  * new with delete and new[] with delete[]. Otherwise bad things can happen,
  * since these allocators may use different memory pools (and new/delete call
- * constructors and destructors). See also g_mem_set_vtable().
+ * constructors and destructors).
  */
 
 
@@ -7585,6 +7614,13 @@
  * certain number of columns, then \%Ns is not a correct solution
  * anyway, since it fails to take wide characters (see g_unichar_iswide())
  * into account.
+ *
+ * Note also that there are various printf() parameters which are platform
+ * dependent. GLib provides platform independent macros for these parameters
+ * which should be used instead. A common example is %G_GUINT64_FORMAT, which
+ * should be used instead of `%llu` or similar parameters for formatting
+ * 64-bit integers. These macros are all named `G_*_FORMAT`; see
+ * [Basic Types][glib-Basic-Types].
  */
 
 
@@ -7837,6 +7873,20 @@
  * and #GAsyncQueue, which are thread-safe and need no further
  * application-level locking to be accessed from multiple threads.
  * Most refcounting functions such as g_object_ref() are also thread-safe.
+ *
+ * A common use for #GThreads is to move a long-running blocking operation out
+ * of the main thread and into a worker thread. For GLib functions, such as
+ * single GIO operations, this is not necessary, and complicates the code.
+ * Instead, the `…_async()` version of the function should be used from the main
+ * thread, eliminating the need for locking and synchronisation between multiple
+ * threads. If an operation does need to be moved to a worker thread, consider
+ * using g_task_run_in_thread(), or a #GThreadPool. #GThreadPool is often a
+ * better choice than #GThread, as it handles thread reuse and task queueing;
+ * #GTask uses this internally.
+ *
+ * However, if multiple blocking operations need to be performed in sequence,
+ * and it is not possible to use #GTask for them, moving them to a worker thread
+ * can clarify the code.
  */
 
 
@@ -9373,7 +9423,7 @@
  * @queue: a #GAsyncQueue
  * @data: the @data to remove from the @queue
  *
- * Remove an item from the queue. This function does not block.
+ * Remove an item from the queue.
  *
  * Returns: %TRUE if the item was removed
  * Since: 2.46
@@ -9385,7 +9435,7 @@
  * @queue: a #GAsyncQueue
  * @data: the @data to remove from the @queue
  *
- * Remove an item from the queue. This function does not block.
+ * Remove an item from the queue.
  *
  * This function must be called while holding the @queue's lock.
  *
@@ -14450,6 +14500,10 @@
  *
  * A convenience function/macro to log an error message.
  *
+ * This is not intended for end user error reporting. Use of #GError is
+ * preferred for that instead, as it allows calling functions to perform actions
+ * conditional on the type of error.
+ *
  * Error messages are always fatal, resulting in a call to
  * abort() to terminate the application. This function will
  * result in a core dump; don't use it for errors you expect.
@@ -16018,7 +16072,7 @@
  * If you supplied a @key_destroy_func when creating the
  * #GHashTable, the old key is freed using that function.
  *
- * Returns: %TRUE of the key did not exist yet
+ * Returns: %TRUE if the key did not exist yet
  */
 
 
@@ -16646,6 +16700,9 @@
  * returns %FALSE it is automatically removed from the list of event
  * sources and will not be called again.
  *
+ * See [memory management of sources][mainloop-memory-management] for details
+ * on how to handle the return value and memory management of @data.
+ *
  * This internally creates a main loop source using g_idle_source_new()
  * and attaches it to the global #GMainContext using g_source_attach(), so
  * the callback will be invoked in whichever thread is running that main
@@ -16668,6 +16725,9 @@
  * events pending.  If the function returns %FALSE it is automatically
  * removed from the list of event sources and will not be called again.
  *
+ * See [memory management of sources][mainloop-memory-management] for details
+ * on how to handle the return value and memory management of @data.
+ *
  * This internally creates a main loop source using g_idle_source_new()
  * and attaches it to the global #GMainContext using g_source_attach(), so
  * the callback will be invoked in whichever thread is running that main
@@ -20688,25 +20748,20 @@
  * This function is useful for avoiding an extra copy of allocated memory returned
  * by a non-GLib-based API.
  *
- * A different allocator can be set using g_mem_set_vtable().
- *
  * Returns: if %TRUE, malloc() and g_malloc() can be mixed.
+ * Deprecated: 2.46: GLib always uses the system malloc, so this function always
+ * returns %TRUE.
  */
 
 
 /**
  * g_mem_profile:
  *
- * Outputs a summary of memory usage.
+ * GLib used to support some tools for memory profiling, but this
+ * no longer works. There are many other useful tools for memory
+ * profiling these days which can be used instead.
  *
- * It outputs the frequency of allocations of different sizes,
- * the total number of bytes which have been allocated,
- * the total number of bytes which have been freed,
- * and the difference between the previous two values, i.e. the number of bytes
- * still in use.
- *
- * Note that this function will not output anything unless you have
- * previously installed the #glib_mem_profiler_table with g_mem_set_vtable().
+ * Deprecated: 2.46: Use other memory profiling tools instead
  */
 
 
@@ -20714,17 +20769,12 @@
  * g_mem_set_vtable:
  * @vtable: table of memory allocation routines.
  *
- * Sets the #GMemVTable to use for memory allocation. You can use this
- * to provide custom memory allocation routines.
- *
- * The @vtable only needs to provide malloc(), realloc(), and free()
- * functions; GLib can provide default implementations of the others.
- * The malloc() and realloc() implementations should return %NULL on
- * failure, GLib will handle error-checking for you. @vtable is copied,
- * so need not persist after this function has been called.
+ * This function used to let you override the memory allocation function.
+ * However, its use was incompatible with the use of global constructors
+ * in GLib and GIO, because those use the GLib allocators before main is
+ * reached. Therefore this function is now deprecated and is just a stub.
  *
- * Note that this function must be called before using any other GLib
- * functions.
+ * Deprecated: 2.46: Use other memory profiling tools instead
  */
 
 
@@ -26709,6 +26759,9 @@
  * should not count on @func being called with @data as its first
  * parameter.
  *
+ * See [memory management of sources][mainloop-memory-management] for details
+ * on how to handle memory management of @data.
+ *
  * Typically, you won't use this function. Instead use functions specific
  * to the type of source you are using.
  */
@@ -26952,13 +27005,8 @@
  * main(). wmain() has a wide character argument vector as parameter.
  *
  * At least currently, mingw doesn't support wmain(), so if you use
- * mingw to develop the spawned program, it will have to call the
- * undocumented function __wgetmainargs() to get the wide character
- * argument vector and environment. See gspawn-win32-helper.c in the
- * GLib sources or init.c in the mingw runtime sources for a prototype
- * for that function. Alternatively, you can retrieve the Win32 system
- * level wide character command line passed to the spawned program
- * using the GetCommandLineW() function.
+ * mingw to develop the spawned program, it should call
+ * g_win32_get_command_line() to get arguments in UTF-8.
  *
  * On Windows the low-level child process creation API CreateProcess()
  * doesn't use argument vectors, but a command line. The C runtime
@@ -27356,6 +27404,10 @@
  * It can be passed to g_hash_table_new() as the @hash_func parameter,
  * when using non-%NULL strings as keys in a #GHashTable.
  *
+ * Note that this function may not be a perfect fit for all use cases.
+ * For example, it produces some hash collisions with strings as short
+ * as 2.
+ *
  * Returns: a hash value corresponding to the key
  */
 
@@ -29795,6 +29847,10 @@
  * If the thread can not be created the program aborts. See
  * g_thread_try_new() if you want to attempt to deal with failures.
  *
+ * If you are using threads to offload (potentially many) short-lived tasks,
+ * #GThreadPool may be more appropriate than manually spawning and tracking
+ * multiple #GThreads.
+ *
  * To free the struct returned by this function, use g_thread_unref().
  * Note that g_thread_join() implicitly unrefs the #GThread as well.
  *
@@ -30463,6 +30519,9 @@
  * timeout is recalculated based on the current time and the given interval
  * (it does not try to 'catch up' time lost in delays).
  *
+ * See [memory management of sources][mainloop-memory-management] for details
+ * on how to handle the return value and memory management of @data.
+ *
  * If you want to have a timer in the "seconds" range and do not care
  * about the exact time of the first call of the timer, use the
  * g_timeout_add_seconds() function; this function allows for more
@@ -30504,6 +30563,9 @@
  * timeout is recalculated based on the current time and the given interval
  * (it does not try to 'catch up' time lost in delays).
  *
+ * See [memory management of sources][mainloop-memory-management] for details
+ * on how to handle the return value and memory management of @data.
+ *
  * This internally creates a main loop source using g_timeout_source_new()
  * and attaches it to the global #GMainContext using g_source_attach(), so
  * the callback will be invoked in whichever thread is running that main
@@ -30537,6 +30599,9 @@
  * of one second. If you need finer precision and have such a timeout,
  * you may want to use g_timeout_add() instead.
  *
+ * See [memory management of sources][mainloop-memory-management] for details
+ * on how to handle the return value and memory management of @data.
+ *
  * The interval given is in terms of monotonic time, not wall clock
  * time.  See g_get_monotonic_time().
  *
@@ -30572,6 +30637,9 @@
  * After each call to the timeout function, the time of the next
  * timeout is recalculated based on the current time and the given @interval
  *
+ * See [memory management of sources][mainloop-memory-management] for details
+ * on how to handle the return value and memory management of @data.
+ *
  * If you want timing more precise than whole seconds, use g_timeout_add()
  * instead.
  *
@@ -33641,7 +33709,7 @@
  * type.  This includes the types %G_VARIANT_TYPE_STRING,
  * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE.
  *
- * The string will always be UTF-8 encoded.
+ * The string will always be UTF-8 encoded, and will never be %NULL.
  *
  * If @length is non-%NULL then the length of the string (in bytes) is
  * returned there.  For trusted values, this information is already
@@ -34679,7 +34747,9 @@
  *
  * Creates a string #GVariant with the contents of @string.
  *
- * @string must be valid UTF-8.
+ * @string must be valid UTF-8, and must not be %NULL. To encode
+ * potentially-%NULL strings, use g_variant_new() with `ms` as the
+ * [format string][gvariant-format-strings-maybe-types].
  *
  * Returns: (transfer none): a floating reference to a new string #GVariant instance
  * Since: 2.24
@@ -34707,7 +34777,8 @@
  *
  * Creates a string #GVariant with the contents of @string.
  *
- * @string must be valid UTF-8.
+ * @string must be valid UTF-8, and must not be %NULL. To encode
+ * potentially-%NULL strings, use this with g_variant_new_maybe().
  *
  * This function consumes @string.  g_free() will be called on @string
  * when it is no longer required.
@@ -35750,6 +35821,10 @@
  *
  * A convenience function/macro to log a warning message.
  *
+ * This is not intended for end user error reporting. Use of #GError is
+ * preferred for that instead, as it allows calling functions to perform actions
+ * conditional on the type of error.
+ *
  * You can make warnings fatal at runtime by setting the `G_DEBUG`
  * environment variable (see
  * [Running GLib Applications](glib-running.html)).
@@ -36227,10 +36302,7 @@
 /**
  * glib_mem_profiler_table:
  *
- * A #GMemVTable containing profiling variants of the memory
- * allocation functions. Use them together with g_mem_profile()
- * in order to get information about the memory allocation pattern
- * of your program.
+ * Deprecated: 2.46: Use other memory profiling tools instead
  */
 
 
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index afbc2d2..c778d2f 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -441,10 +441,10 @@
  * separately (typically by using #GArray or #GPtrArray) and put a pointer
  * to the buffer in the structure.
  *
- * A final word about type names: Such an identifier needs to be at least
- * three characters long. There is no upper length limit. The first character
- * needs to be a letter (a-z or A-Z) or an underscore '_'. Subsequent
- * characters can be letters, numbers or any of '-_+'.
+ * As mentioned in the [GType conventions][gtype-conventions], type names must
+ * be at least three characters long. There is no upper length limit. The first
+ * character must be a letter (a–z or A–Z) or an underscore (‘_’). Subsequent
+ * characters can be letters, numbers or any of ‘-_+’.
  */
 
 
@@ -551,6 +551,12 @@
  * construction and destruction, property access methods, and signal
  * support.  Signals are described in detail [here][gobject-Signals].
  *
+ * For a tutorial on implementing a new GObject class, see [How to define and
+ * implement a new GObject][howto-gobject]. For a list of naming conventions for
+ * GObjects and their methods, see the [GType conventions][gtype-conventions].
+ * For the high-level concepts behind GObject, read [Instantiable classed types:
+ * Objects][gtype-instantiable-classed].
+ *
  * ## Floating references # {#floating-ref}
  *
  * GInitiallyUnowned is derived from GObject. The only difference between
@@ -686,6 +692,32 @@
  * Specification of no detail argument for signal handlers (omission of the
  * detail part of the signal specification upon connection) serves as a
  * wildcard and matches any detail argument passed in to emission.
+ *
+ * ## Memory management of signal handlers # {#signal-memory-management}
+ *
+ * If you are connecting handlers to signals and using a #GObject instance as
+ * your signal handler user data, you should remember to pair calls to
+ * g_signal_connect() with calls to g_signal_handler_disconnect() or
+ * g_signal_handlers_disconnect_by_func(). While signal handlers are
+ * automatically disconnected when the object emitting the signal is finalised,
+ * they are not automatically disconnected when the signal handler user data is
+ * destroyed. If this user data is a #GObject instance, using it from a
+ * signal handler after it has been finalised is an error.
+ *
+ * There are two strategies for managing such user data. The first is to
+ * disconnect the signal handler (using g_signal_handler_disconnect() or
+ * g_signal_handlers_disconnect_by_func()) when the user data (object) is
+ * finalised; this has to be implemented manually. For non-threaded programs,
+ * g_signal_connect_object() can be used to implement this automatically.
+ * Currently, however, it is unsafe to use in threaded programs.
+ *
+ * The second is to hold a strong reference on the user data until after the
+ * signal is disconnected for other reasons. This can be implemented
+ * automatically using g_signal_connect_data().
+ *
+ * The first approach is recommended, as the second approach can result in
+ * effective memory leaks of the user data if the signal handler is never
+ * disconnected for some reason.
  */
 
 
@@ -869,22 +901,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.
  */
 
 
@@ -944,39 +971,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)`.
  */
 
 
@@ -1001,20 +1012,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)`.
  */
 
 
@@ -1039,20 +1046,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)`.
  */
 
 
@@ -1077,20 +1080,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)`.
  */
 
 
@@ -1115,20 +1114,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)`.
  */
 
 
@@ -1153,20 +1148,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..
  */
 
 
@@ -1191,20 +1182,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.
  */
 
 
@@ -1229,20 +1216,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)`.
  */
 
 
@@ -1267,20 +1250,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)`.
  */
 
 
@@ -1305,20 +1284,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)`.
  */
 
 
@@ -1343,20 +1318,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)`.
  */
 
 
@@ -1381,20 +1352,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)`.
  */
 
 
@@ -1419,24 +1386,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)`.
  */
 
 
@@ -1461,20 +1420,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)`.
  */
 
 
@@ -1499,20 +1454,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)`.
  */
 
 
@@ -1537,39 +1488,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)`.
  */
 
 
@@ -1613,20 +1556,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)`.
  */
 
 
@@ -1651,20 +1590,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
  */
 
 
@@ -1689,19 +1626,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)`.
  */