Update glib annotations from glib 2.41.1

3 files changed, 140 insertions, 31 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 5c45963c..2e5c60b3 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -4474,7 +4474,7 @@
  * processes owned by the same uid as the server, you would use a
  * signal handler like the following:
  *
- * |[
+ * |[<!-- language="C" -->
  * static gboolean
  * on_authorize_authenticated_peer (GDBusAuthObserver *observer,
  *                                  GIOStream         *stream,
@@ -32391,8 +32391,9 @@
  * @condition: a #GIOCondition mask to monitor
  * @cancellable: (allow-none): a %GCancellable or %NULL
  *
- * Creates a %GSource that can be attached to a %GMainContext to monitor
- * for the availability of the specified @condition on the socket.
+ * Creates a #GSource that can be attached to a %GMainContext to monitor
+ * for the availability of the specified @condition on the socket. The #GSource
+ * keeps a reference to the @socket.
  *
  * The callback on the source is of the #GSocketSourceFunc type.
  *
@@ -32965,6 +32966,11 @@
  * useful if you're listening on multiple addresses and do
  * different things depending on what address is connected to.
  *
+ * The @socket will not be automatically closed when the @listener is finalized
+ * unless the listener held the final reference to the socket. Before GLib 2.42,
+ * the @socket was automatically closed on finalization of the @listener, even
+ * if references to it were held elsewhere.
+ *
  * Returns: %TRUE on success, %FALSE on error.
  * Since: 2.22
  */
@@ -34404,8 +34410,8 @@
  * g_subprocess_new: (skip)
  * @flags: flags that define the behaviour of the subprocess
  * @error: (allow-none): return location for an error, or %NULL
- * @argv0: first commandline argument to pass to the subprocess,
- *     followed by more arguments, followed by %NULL
+ * @argv0: first commandline argument to pass to the subprocess
+ * @...: more commandline arguments, followed by %NULL
  *
  * Create a new process with the given flags and varargs argument
  * list.  By default, matching the g_spawn_async() defaults, the
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index dacb1e2c..84ee1e0b 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -986,7 +986,7 @@
  *     This flag cannot be changed.
  * @G_IO_FLAG_IS_WRITABLE: indicates that the io channel is writable.
  *     This flag cannot be changed.
- * G_IO_FLAG_IS_WRITEABLE: a misspelled version of @G_IO_FLAG_IS_WRITABLE
+ * @G_IO_FLAG_IS_WRITEABLE: a misspelled version of @G_IO_FLAG_IS_WRITABLE
  *     that existed before the spelling was fixed in GLib 2.30. It is kept
  *     here for compatibility reasons. Deprecated since 2.30
  * @G_IO_FLAG_IS_SEEKABLE: indicates that the io channel is seekable,
@@ -2624,7 +2624,7 @@
  *
  * ## Using a stack-allocated GVariantDict
  *
- * |[
+ * |[<!-- language="C" -->
  *   GVariant *
  *   add_to_count (GVariant  *orig,
  *                 GError   **error)
@@ -2648,7 +2648,7 @@
  *
  * ## Using heap-allocated GVariantDict
  *
- * |[
+ * |[<!-- language="C" -->
  *   GVariant *
  *   add_to_count (GVariant  *orig,
  *                 GError   **error)
@@ -2796,6 +2796,15 @@
 
 
 /**
+ * G_CSET_DIGITS:
+ *
+ * The set of ASCII digits.
+ * Used for specifying valid identifier characters
+ * in #GScannerConfig.
+ */
+
+
+/**
  * G_CSET_LATINC:
  *
  * The set of uppercase ISO 8859-1 alphabet characters
@@ -3532,6 +3541,13 @@
 
 
 /**
+ * G_HAVE_GNUC_VISIBILITY:
+ *
+ * Defined to 1 if gcc-style visibility handling is supported.
+ */
+
+
+/**
  * G_HOOK:
  * @hook: a pointer
  *
@@ -4041,6 +4057,14 @@
 
 
 /**
+ * G_LOG_LEVEL_USER_SHIFT:
+ *
+ * Log levels below 1<<G_LOG_LEVEL_USER_SHIFT are used by GLib.
+ * Higher bits can be used for user-defined log levels.
+ */
+
+
+/**
  * G_MAXDOUBLE:
  *
  * The maximum value which can be held in a #gdouble.
@@ -7336,6 +7360,14 @@
  * SECTION:shell
  * @title: Shell-related Utilities
  * @short_description: shell-like commandline handling
+ *
+ * GLib provides the functions g_shell_quote() and g_shell_unquote()
+ * to handle shell-like quoting in strings. The function g_shell_parse_argv()
+ * parses a string similar to the way a POSIX shell (/bin/sh) would.
+ *
+ * Note that string handling in shells has many obscure and historical
+ * corner-cases which these functions do not necessarily reproduce. They
+ * are good enough in practice, though.
  */
 
 
@@ -7343,6 +7375,17 @@
  * SECTION:spawn
  * @Short_description: process launching
  * @Title: Spawning Processes
+ *
+ * GLib supports spawning of processes with an API that is more
+ * convenient than the bare UNIX fork() and exec().
+ *
+ * The g_spawn family of functions has synchronous (g_spawn_sync())
+ * and asynchronous variants (g_spawn_async(), g_spawn_async_with_pipes()),
+ * as well as convenience variants that take a complete shell-like
+ * commandline (g_spawn_command_line_sync(), g_spawn_command_line_async()).
+ *
+ * See #GSubprocess in GIO for a higher-level API that provides
+ * stream interfaces for communication with child processes.
  */
 
 
@@ -11606,7 +11649,7 @@
 /**
  * g_convert:
  * @str: the string to convert
- * @len: the length of the string, or -1 if the string is
+ * @len: the length of the string in bytes, or -1 if the string is
  *                 nul-terminated (Note that some encodings may allow nul
  *                 bytes to occur inside strings. In that case, using -1
  *                 for the @len parameter is unsafe)
@@ -11649,7 +11692,7 @@
 /**
  * g_convert_with_fallback:
  * @str: the string to convert
- * @len: the length of the string, or -1 if the string is
+ * @len: the length of the string in bytes, or -1 if the string is
  *                 nul-terminated (Note that some encodings may allow nul
  *                 bytes to occur inside strings. In that case, using -1
  *                 for the @len parameter is unsafe)
@@ -11697,7 +11740,7 @@
 /**
  * g_convert_with_iconv:
  * @str: the string to convert
- * @len: the length of the string, or -1 if the string is
+ * @len: the length of the string in bytes, or -1 if the string is
  *                 nul-terminated (Note that some encodings may allow nul
  *                 bytes to occur inside strings. In that case, using -1
  *                 for the @len parameter is unsafe)
@@ -15378,7 +15421,7 @@
  * values are freed yourself.
  *
  * It is safe to continue iterating the #GHashTable afterward:
- * |[
+ * |[<!-- language="C" -->
  * while (g_hash_table_iter_next (&iter, &key, &value))
  *   {
  *     if (condition)
@@ -16405,13 +16448,6 @@
 
 
 /**
- * g_io_channel_error_quark:
- *
- * Returns: the quark used as %G_IO_CHANNEL_ERROR
- */
-
-
-/**
  * g_io_channel_flush:
  * @channel: a #GIOChannel
  * @error: location to store an error of type #GIOChannelError
@@ -33608,7 +33644,7 @@
  * specified in @format_string. This can be achieved by casting them. See
  * the [GVariant varargs documentation][gvariant-varargs].
  *
- * |[
+ * |[<!-- language="C" -->
  * MyFlags some_flags = FLAG_ONE | FLAG_TWO;
  * const gchar *some_strings[] = { "a", "b", "c", NULL };
  * GVariant *new_variant;
@@ -34270,6 +34306,8 @@
 /**
  * g_variant_parser_get_error_quark:
  *
+ * Same as g_variant_error_quark().
+ *
  * Deprecated: Use g_variant_parse_error_quark() instead.
  */
 
@@ -35462,6 +35500,17 @@
 
 
 /**
+ * glib_binary_age:
+ *
+ * The binary age of the GLib library.
+ * Defines how far back backwards compatibility reaches.
+ *
+ * An integer variable exported from the library linked
+ * against at application run time.
+ */
+
+
+/**
  * glib_check_version:
  * @required_major: the required major version
  * @required_minor: the required minor version
@@ -35503,6 +35552,27 @@
 
 
 /**
+ * glib_interface_age:
+ *
+ * The interface age of the GLib library.
+ * Defines how far back the API has last been extended.
+ *
+ * An integer variable exported from the library linked
+ * against at application run time.
+ */
+
+
+/**
+ * glib_major_version:
+ *
+ * The major version of the GLib library.
+ *
+ * An integer variable exported from the library linked
+ * against at application run time.
+ */
+
+
+/**
  * glib_mem_profiler_table:
  *
  * A #GMemVTable containing profiling variants of the memory
@@ -35513,6 +35583,26 @@
 
 
 /**
+ * glib_micro_version:
+ *
+ * The micro version number of the GLib library.
+ *
+ * An integer variable exported from the library linked
+ * against at application run time.
+ */
+
+
+/**
+ * glib_minor_version:
+ *
+ * The minor version number of the GLib library.
+ *
+ * An integer variable exported from the library linked
+ * against at application run time.
+ */
+
+
+/**
  * glib_pgettext:
  * @msgctxtid: a combined message context and message id, separated
  *   by a \004 character
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index a4bfed0f..b2973238 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -1875,8 +1875,12 @@
  * @pspecs: (array length=n_pspecs): the #GParamSpecs array
  *   defining the new properties
  *
- * Installs new properties from an array of #GParamSpecs. This is
- * usually done in the class initializer.
+ * Installs new properties from an array of #GParamSpecs.
+ *
+ * All properties should be installed during the class initializer.  It
+ * is possible to install properties after that, but doing so is not
+ * recommend, and specifically, is not guaranteed to be thread-safe vs.
+ * use of properties on the same type on other threads.
  *
  * The property id of each property is the index of each #GParamSpec in
  * the @pspecs array.
@@ -1943,7 +1947,12 @@
  * @property_id: the id for the new property
  * @pspec: the #GParamSpec for the new property
  *
- * Installs a new property. This is usually done in the class initializer.
+ * Installs a new property.
+ *
+ * All properties should be installed during the class initializer.  It
+ * is possible to install properties after that, but doing so is not
+ * recommend, and specifically, is not guaranteed to be thread-safe vs.
+ * use of properties on the same type on other threads.
  *
  * Note that it is possible to redefine a property in a derived class,
  * by installing a property with the same name. This can be useful at times,
@@ -3876,7 +3885,11 @@
 
 /**
  * g_signal_handlers_destroy:
- * @instance: (type GObject.Object): The instance where a signal handler is sought.
+ * @instance: (type GObject.Object): The instance whose signal handlers are destroyed
+ *
+ * Destroy all signal handlers of a type instance. This function is
+ * an implementation detail of the #GObject dispose implementation,
+ * and should not be used outside of the type system.
  */
 
 
@@ -4453,8 +4466,7 @@
  *   my_object->priv = G_TYPE_INSTANCE_GET_PRIVATE (my_object,
  *                                                  MY_TYPE_OBJECT,
  *                                                  MyObjectPrivate);
- *   /<!-- -->* my_object->priv->some_field will be
- *    * automatically initialised to 0 *<!-- -->/
+ *   // my_object->priv->some_field will be automatically initialised to 0
  * }
  *
  * static int
@@ -5701,12 +5713,13 @@
 
 /**
  * g_value_peek_pointer:
- * @value: An initialized #GValue structure.
+ * @value: An initialized #GValue structure
+ *
+ * Returns the value contents as pointer. This function asserts that
+ * g_value_fits_pointer() returned %TRUE for the passed in value.
+ * This is an internal function introduced mainly for C marshallers.
  *
- * Returns: (transfer none): the value contents as pointer. This
- * function asserts that g_value_fits_pointer() returned %TRUE for the
- * passed in value.  This is an internal function introduced mainly
- * for C marshallers.
+ * Returns: (transfer none): the value contents as pointer
  */