Update the GLib documentation

Up to the 2.69.1 tag.

4 files changed, 1594 insertions, 525 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index c1ffdd09..eec568cf 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -746,6 +746,15 @@
  * of the other peer here after the connection has been successfully
  * initialized.
  *
+ * Note that the
+ * [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses)
+ * uses the term ‘UUID’ to refer to this, whereas GLib consistently uses the
+ * term ‘GUID’ for historical reasons.
+ *
+ * Despite its name, the format of #GDBusConnection:guid does not follow
+ * [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122) or the Microsoft
+ * GUID format.
+ *
  * Since: 2.26
  */
 
@@ -1426,7 +1435,9 @@
 /**
  * GDBusServer:guid:
  *
- * The guid of the server.
+ * The GUID of the server.
+ *
+ * See #GDBusConnection:guid for more details.
  *
  * Since: 2.26
  */
@@ -1443,27 +1454,27 @@
 
 
 /**
- * GDataOutputStream:byte-order:
+ * GDataInputStream:byte-order:
  *
- * Determines the byte ordering that is used when writing
- * multi-byte entities (such as integers) to the stream.
+ * The :byte-order property determines the byte ordering that
+ * is used when reading multi-byte entities (such as integers)
+ * from the stream.
  */
 
 
 /**
- * GDataStream:byte-order:
+ * GDataInputStream:newline-type:
  *
- * The ::byte-order property determines the byte ordering that
- * is used when reading multi-byte entities (such as integers)
- * from the stream.
+ * The :newline-type property determines what is considered
+ * as a line ending when reading complete lines from the stream.
  */
 
 
 /**
- * GDataStream:newline-type:
+ * GDataOutputStream:byte-order:
  *
- * The :newline-type property determines what is considered
- * as a line ending when reading complete lines from the stream.
+ * Determines the byte ordering that is used when writing
+ * multi-byte entities (such as integers) to the stream.
  */
 
 
@@ -1680,6 +1691,15 @@
 
 
 /**
+ * GDtlsConnection:ciphersuite-name: (nullable)
+ *
+ * The name of the DTLS ciphersuite in use. See g_dtls_connection_get_ciphersuite_name().
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * GDtlsConnection:database: (nullable)
  *
  * The certificate database to use when verifying this TLS connection.
@@ -1740,6 +1760,15 @@
 
 
 /**
+ * GDtlsConnection:protocol-version:
+ *
+ * The DTLS protocol version in use. See g_dtls_connection_get_protocol_version().
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * GDtlsConnection:rehandshake-mode:
  *
  * The rehandshaking mode. See
@@ -2654,6 +2683,35 @@
 
 
 /**
+ * GPowerProfileMonitor:
+ *
+ * #GPowerProfileMonitor monitors system power profile and notifies on
+ * changes.
+ *
+ * Since: 2.70
+ */
+
+
+/**
+ * GPowerProfileMonitor:power-saver-enabled:
+ *
+ * Whether “Power Saver” mode is enabled on the system.
+ *
+ * Since: 2.70
+ */
+
+
+/**
+ * GPowerProfileMonitorInterface:
+ * @g_iface: The parent interface.
+ *
+ * The virtual function table for #GPowerProfileMonitor.
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * GPropertyAction:
  *
  * This type is opaque.
@@ -3615,6 +3673,26 @@
 
 
 /**
+ * GTlsCertificate:dns-names: (nullable) (element-type GBytes) (transfer container)
+ *
+ * The DNS names from the certificate's Subject Alternative Names (SANs),
+ * %NULL if unavailable.
+ *
+ * Since: 2.70
+ */
+
+
+/**
+ * GTlsCertificate:ip-addresses: (nullable) (element-type GInetAddress) (transfer container)
+ *
+ * The IP addresses from the certificate's Subject Alternative Names (SANs),
+ * %NULL if unavailable.
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * GTlsCertificate:issuer:
  *
  * A #GTlsCertificate representing the entity that issued this
@@ -3622,17 +3700,59 @@
  * self-signed, or else the certificate of the issuer is not
  * available.
  *
+ * Beware the issuer certificate may not be the same as the
+ * certificate that would actually be used to construct a valid
+ * certification path during certificate verification.
+ * [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains
+ * why an issuer certificate cannot be naively assumed to be part of the
+ * the certification path (though GLib's TLS backends may not follow the
+ * path building strategies outlined in this RFC). Due to the complexity
+ * of certification path building, GLib does not provide any way to know
+ * which certification path will actually be used. Accordingly, this
+ * property cannot be used to make security-related decisions. Only
+ * GLib itself should make security decisions about TLS certificates.
+ *
  * Since: 2.28
  */
 
 
 /**
+ * GTlsCertificate:issuer-name: (nullable)
+ *
+ * The issuer from the certificate,
+ * %NULL if unavailable.
+ *
+ * Since: 2.70
+ */
+
+
+/**
+ * GTlsCertificate:not-valid-after: (nullable)
+ *
+ * The time at which this cert is no longer valid,
+ * %NULL if unavailable.
+ *
+ * Since: 2.70
+ */
+
+
+/**
+ * GTlsCertificate:not-valid-before: (nullable)
+ *
+ * The time at which this cert is considered to be valid,
+ * %NULL if unavailable.
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * GTlsCertificate:pkcs11-uri: (nullable)
  *
- * A URI referencing the PKCS \#11 objects containing an X.509 certificate
- * and optionally a private key.
+ * A URI referencing the [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html)
+ * objects containing an X.509 certificate and optionally a private key.
  *
- * If %NULL the certificate is either not backed by PKCS \#11 or the
+ * If %NULL, the certificate is either not backed by PKCS \#11 or the
  * #GTlsBackend does not support PKCS \#11.
  *
  * Since: 2.68
@@ -3640,35 +3760,51 @@
 
 
 /**
- * GTlsCertificate:private-key:
+ * GTlsCertificate:private-key: (nullable)
  *
  * The DER (binary) encoded representation of the certificate's
- * private key, in either PKCS#1 format or unencrypted PKCS#8
- * format. This property (or the #GTlsCertificate:private-key-pem
- * property) can be set when constructing a key (eg, from a file),
- * but cannot be read.
- *
- * PKCS#8 format is supported since 2.32; earlier releases only
- * support PKCS#1. You can use the `openssl rsa`
- * tool to convert PKCS#8 keys to PKCS#1.
+ * private key, in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017)
+ * or unencrypted [PKCS \#8 format.](https://datatracker.ietf.org/doc/html/rfc5208)
+ * PKCS \#8 format is supported since 2.32; earlier releases only
+ * support PKCS \#1. You can use the `openssl rsa` tool to convert
+ * PKCS \#8 keys to PKCS \#1.
+ *
+ * This property (or the #GTlsCertificate:private-key-pem property)
+ * can be set when constructing a key (for example, from a file).
+ * Since GLib 2.70, it is now also readable; however, be aware that if
+ * the private key is backed by a PKCS \#11 URI – for example, if it
+ * is stored on a smartcard – then this property will be %NULL. If so,
+ * the private key must be referenced via its PKCS \#11 URI,
+ * #GTlsCertificate:private-key-pkcs11-uri. You must check both
+ * properties to see if the certificate really has a private key.
+ * When this property is read, the output format will be unencrypted
+ * PKCS \#8.
  *
  * Since: 2.28
  */
 
 
 /**
- * GTlsCertificate:private-key-pem:
+ * GTlsCertificate:private-key-pem: (nullable)
  *
  * The PEM (ASCII) encoded representation of the certificate's
- * private key in either PKCS#1 format ("`BEGIN RSA PRIVATE
- * KEY`") or unencrypted PKCS#8 format ("`BEGIN
- * PRIVATE KEY`"). This property (or the
- * #GTlsCertificate:private-key property) can be set when
- * constructing a key (eg, from a file), but cannot be read.
- *
- * PKCS#8 format is supported since 2.32; earlier releases only
- * support PKCS#1. You can use the `openssl rsa`
- * tool to convert PKCS#8 keys to PKCS#1.
+ * private key in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017)
+ * ("`BEGIN RSA PRIVATE KEY`") or unencrypted
+ * [PKCS \#8 format](https://datatracker.ietf.org/doc/html/rfc5208)
+ * ("`BEGIN PRIVATE KEY`"). PKCS \#8 format is supported since 2.32;
+ * earlier releases only support PKCS \#1. You can use the `openssl rsa`
+ * tool to convert PKCS \#8 keys to PKCS \#1.
+ *
+ * This property (or the #GTlsCertificate:private-key property)
+ * can be set when constructing a key (for example, from a file).
+ * Since GLib 2.70, it is now also readable; however, be aware that if
+ * the private key is backed by a PKCS \#11 URI - for example, if it
+ * is stored on a smartcard - then this property will be %NULL. If so,
+ * the private key must be referenced via its PKCS \#11 URI,
+ * #GTlsCertificate:private-key-pkcs11-uri. You must check both
+ * properties to see if the certificate really has a private key.
+ * When this property is read, the output format will be unencrypted
+ * PKCS \#8.
  *
  * Since: 2.28
  */
@@ -3677,13 +3813,24 @@
 /**
  * GTlsCertificate:private-key-pkcs11-uri: (nullable)
  *
- * A URI referencing a PKCS \#11 object containing a private key.
+ * A URI referencing a [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html)
+ * object containing a private key.
  *
  * Since: 2.68
  */
 
 
 /**
+ * GTlsCertificate:subject-name: (nullable)
+ *
+ * The subject from the cert,
+ * %NULL if unavailable.
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * GTlsClientConnection:
  *
  * Abstract base class for the backend-specific client connection
@@ -3846,6 +3993,15 @@
 
 
 /**
+ * GTlsConnection:ciphersuite-name: (nullable)
+ *
+ * The name of the TLS ciphersuite in use. See g_tls_connection_get_ciphersuite_name().
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * GTlsConnection:database: (nullable)
  *
  * The certificate database to use when verifying this TLS connection.
@@ -3906,6 +4062,15 @@
 
 
 /**
+ * GTlsConnection:protocol-version:
+ *
+ * The TLS protocol version in use. See g_tls_connection_get_protocol_version().
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * GTlsConnection:rehandshake-mode:
  *
  * The rehandshaking mode. See
@@ -4841,13 +5006,13 @@
  * respectively.
  *
  * For an example of opening files with a GApplication, see
- * [gapplication-example-open.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-open.c).
+ * [gapplication-example-open.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-open.c).
  *
  * For an example of using actions with GApplication, see
- * [gapplication-example-actions.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-actions.c).
+ * [gapplication-example-actions.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-actions.c).
  *
  * For an example of using extra D-Bus hooks with GApplication, see
- * [gapplication-example-dbushooks.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-dbushooks.c).
+ * [gapplication-example-dbushooks.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-dbushooks.c).
  */
 
 
@@ -4918,7 +5083,7 @@
  * }
  * ]|
  * The complete example can be found here:
- * [gapplication-example-cmdline.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline.c)
+ * [gapplication-example-cmdline.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline.c)
  *
  * In more complicated cases, the handling of the comandline can be
  * split between the launcher and the primary instance.
@@ -4969,7 +5134,7 @@
  * instance.
  *
  * The complete example can be found here:
- * [gapplication-example-cmdline2.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline2.c)
+ * [gapplication-example-cmdline2.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c)
  *
  * If handling the commandline requires a lot of work, it may
  * be better to defer it.
@@ -5011,7 +5176,7 @@
  * hold the application until you are done with the commandline.
  *
  * The complete example can be found here:
- * [gapplication-example-cmdline3.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline3.c)
+ * [gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c)
  */
 
 
@@ -5618,22 +5783,22 @@
  * ## An example D-Bus server # {#gdbus-server}
  *
  * Here is an example for a D-Bus server:
- * [gdbus-example-server.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-server.c)
+ * [gdbus-example-server.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-server.c)
  *
  * ## An example for exporting a subtree # {#gdbus-subtree-server}
  *
  * Here is an example for exporting a subtree:
- * [gdbus-example-subtree.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-subtree.c)
+ * [gdbus-example-subtree.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-subtree.c)
  *
  * ## An example for file descriptor passing # {#gdbus-unix-fd-client}
  *
  * Here is an example for passing UNIX file descriptors:
- * [gdbus-unix-fd-client.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-unix-fd-client.c)
+ * [gdbus-unix-fd-client.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-unix-fd-client.c)
  *
  * ## An example for exporting a GObject # {#gdbus-export}
  *
  * Here is an example for exporting a #GObject:
- * [gdbus-example-export.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-export.c)
+ * [gdbus-example-export.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-export.c)
  */
 
 
@@ -5796,7 +5961,7 @@
  * Convenience API for owning bus names.
  *
  * A simple example for owning a name can be found in
- * [gdbus-example-own-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-own-name.c)
+ * [gdbus-example-own-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-own-name.c)
  */
 
 
@@ -5809,7 +5974,7 @@
  * Convenience API for watching bus names.
  *
  * A simple example for watching a name can be found in
- * [gdbus-example-watch-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-name.c)
+ * [gdbus-example-watch-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-name.c)
  */
 
 
@@ -6007,6 +6172,13 @@
  * the message bus launching an owner (unless
  * %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).
  *
+ * If the proxy is for a stateless D-Bus service, where the name owner may
+ * be started and stopped between calls, the #GDBusProxy:g-name-owner tracking
+ * of #GDBusProxy will cause the proxy to drop signal and property changes from
+ * the service after it has restarted for the first time. When interacting
+ * with a stateless D-Bus service, do not use #GDBusProxy — use direct D-Bus
+ * method calls and signal connections.
+ *
  * The generic #GDBusProxy::g-properties-changed and
  * #GDBusProxy::g-signal signals are not very convenient to work with.
  * Therefore, the recommended way of working with proxies is to subclass
@@ -6021,7 +6193,7 @@
  * of the thread where the instance was constructed.
  *
  * An example using a proxy for a well-known name can be found in
- * [gdbus-example-watch-proxy.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-proxy.c)
+ * [gdbus-example-watch-proxy.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-proxy.c)
  */
 
 
@@ -6040,7 +6212,7 @@
  * session or system bus, you should instead use g_bus_own_name().
  *
  * An example of peer-to-peer communication with GDBus can be found
- * in [gdbus-example-peer.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-peer.c).
+ * in [gdbus-example-peer.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c).
  *
  * Note that a minimal #GDBusServer will accept connections from any
  * peer. In many use-cases it will be necessary to add a #GDBusAuthObserver
@@ -6481,6 +6653,11 @@
  * g_file_query_writable_namespaces() to discover the settable attributes
  * of a particular file at runtime.
  *
+ * The direct accessors, such as g_file_info_get_name(), are slightly more
+ * optimized than the generic attribute accessors, such as
+ * g_file_info_get_attribute_byte_string().This optimization will matter
+ * only if calling the API in a tight loop.
+ *
  * #GFileAttributeMatcher allows for searching through a #GFileInfo for
  * attributes.
  */
@@ -6943,13 +7120,14 @@
  * There is also an implementation for use inside Flatpak sandboxes.
  *
  * Possible actions to take when the signal is received are:
- * - Free caches
- * - Save files that haven't been looked at in a while to disk, ready to be reopened when needed
- * - Run a garbage collection cycle
- * - Try and compress fragmented allocations
- * - Exit on idle if the process has no reason to stay around
- * - Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to
- *   the kernel (if supported by your libc)
+ *
+ *  - Free caches
+ *  - Save files that haven't been looked at in a while to disk, ready to be reopened when needed
+ *  - Run a garbage collection cycle
+ *  - Try and compress fragmented allocations
+ *  - Exit on idle if the process has no reason to stay around
+ *  - Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to
+ *    the kernel (if supported by your libc)
  *
  * Note that some actions may not always improve system performance, and so
  * should be profiled for your application. `malloc_trim()`, for example, may
@@ -7315,6 +7493,29 @@
  * not running, applications using #GNotification should be able to be
  * started as a D-Bus service, using #GApplication.
  *
+ * In order for #GNotification to work, the application must have installed
+ * a `.desktop` file. For example:
+ * |[
+ *  [Desktop Entry]
+ *   Name=Test Application
+ *   Comment=Description of what Test Application does
+ *   Exec=gnome-test-application
+ *   Icon=org.gnome.TestApplication
+ *   Terminal=false
+ *   Type=Application
+ *   Categories=GNOME;GTK;TestApplication Category;
+ *   StartupNotify=true
+ *   DBusActivatable=true
+ *   X-GNOME-UsesNotifications=true
+ * ]|
+ *
+ * The `X-GNOME-UsesNotifications` key indicates to GNOME Control Center
+ * that this application uses notifications, so it can be listed in the
+ * Control Center’s ‘Notifications’ panel.
+ *
+ * The `.desktop` file must be named as `org.gnome.TestApplication.desktop`,
+ * where `org.gnome.TestApplication` is the ID passed to g_application_new().
+ *
  * User interaction with a notification (either the default action, or
  * buttons) must be associated with actions on the application (ie:
  * "app." actions).  It is not possible to route user interaction
@@ -7413,6 +7614,39 @@
 
 
 /**
+ * SECTION:gpowerprofilemonitor
+ * @title: GPowerProfileMonitor
+ * @short_description: Power profile monitor
+ * @include: gio/gio.h
+ *
+ * #GPowerProfileMonitor makes it possible for applications as well as OS components
+ * to monitor system power profiles and act upon them. It currently only exports
+ * whether the system is in “Power Saver” mode (known as “Low Power” mode on
+ * some systems).
+ *
+ * When in “Low Power” mode, it is recommended that applications:
+ * - disabling automatic downloads
+ * - reduce the rate of refresh from online sources such as calendar or
+ *   email synchronisation
+ * - if the application has expensive visual effects, reduce them
+ *
+ * It is also likely that OS components providing services to applications will
+ * lower their own background activity, for the sake of the system.
+ *
+ * There are a variety of tools that exist for power consumption analysis, but those
+ * usually depend on the OS and hardware used. On Linux, one could use `upower` to
+ * monitor the battery discharge rate, `powertop` to check on the background activity
+ * or activity at all), `sysprof` to inspect CPU usage, and `intel_gpu_time` to
+ * profile GPU usage.
+ *
+ * Don't forget to disconnect the #GPowerProfileMonitor::notify::power-saver-enabled
+ * signal, and unref the #GPowerProfileMonitor itself when exiting.
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * SECTION:gpropertyaction
  * @title: GPropertyAction
  * @short_description: A GAction reflecting a GObject property
@@ -7835,7 +8069,7 @@
  * utility. The input is a schema description in an XML format.
  *
  * A DTD for the gschema XML format can be found here:
- * [gschema.dtd](https://git.gnome.org/browse/glib/tree/gio/gschema.dtd)
+ * [gschema.dtd](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/gschema.dtd)
  *
  * The [glib-compile-schemas][glib-compile-schemas] tool expects schema
  * files to have the extension `.gschema.xml`.
@@ -9430,7 +9664,7 @@
  *
  * An example of a test fixture for D-Bus services can be found
  * here:
- * [gdbus-test-fixture.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-test-fixture.c)
+ * [gdbus-test-fixture.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-test-fixture.c)
  *
  * Note that these examples only deal with isolating the D-Bus aspect of your
  * service. To successfully run isolated unit tests on your service you may need
@@ -9982,7 +10216,7 @@
 
 
 /**
- * SECTION:gzcompressor
+ * SECTION:gzlibcompressor
  * @short_description: Zlib compressor
  * @include: gio/gio.h
  *
@@ -9992,7 +10226,7 @@
 
 
 /**
- * SECTION:gzdecompressor
+ * SECTION:gzlibdecompressor
  * @short_description: Zlib decompressor
  * @include: gio/gio.h
  *
@@ -12205,6 +12439,8 @@
  *
  * To cancel the busy indication, use g_application_unmark_busy().
  *
+ * The application must be registered before calling this function.
+ *
  * Since: 2.38
  */
 
@@ -12374,7 +12610,7 @@
  * and override local_command_line(). In this case, you most likely want
  * to return %TRUE from your local_command_line() implementation to
  * suppress the default handling. See
- * [gapplication-example-cmdline2.c][gapplication-example-cmdline2]
+ * [gapplication-example-cmdline2.c][https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c]
  * for an example.
  *
  * If, after the above is done, the use count of the application is zero
@@ -15274,7 +15510,7 @@
  * If @info is statically allocated does nothing. Otherwise increases
  * the reference count.
  *
- * Returns: The same @info.
+ * Returns: (not nullable): The same @info.
  * Since: 2.26
  */
 
@@ -15298,7 +15534,7 @@
  * If @info is statically allocated does nothing. Otherwise increases
  * the reference count.
  *
- * Returns: The same @info.
+ * Returns: (not nullable): The same @info.
  * Since: 2.26
  */
 
@@ -16544,6 +16780,9 @@
  * g_dbus_connection_signal_subscribe() is called, in order to avoid memory
  * leaks through callbacks queued on the #GMainContext after it’s stopped being
  * iterated.
+ * Alternatively, any idle source with a priority lower than %G_PRIORITY_DEFAULT
+ * that was scheduled after unsubscription, also indicates that all resources
+ * of this subscription are released.
  *
  * Since: 2.26
  */
@@ -16845,8 +17084,14 @@
  * Generate a D-Bus GUID that can be used with
  * e.g. g_dbus_connection_new().
  *
- * See the D-Bus specification regarding what strings are valid D-Bus
- * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
+ * See the
+ * [D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#uuids)
+ * regarding what strings are valid D-Bus GUIDs. The specification refers to
+ * these as ‘UUIDs’ whereas GLib (for historical reasons) refers to them as
+ * ‘GUIDs’. The terms are interchangeable.
+ *
+ * Note that D-Bus GUIDs do not follow
+ * [RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122).
  *
  * Returns: A valid D-Bus GUID. Free with g_free().
  * Since: 2.26
@@ -17055,7 +17300,7 @@
  * If @info is statically allocated does nothing. Otherwise increases
  * the reference count.
  *
- * Returns: The same @info.
+ * Returns: (not nullable): The same @info.
  * Since: 2.26
  */
 
@@ -17278,15 +17523,30 @@
 
 
 /**
+ * g_dbus_is_error_name:
+ * @string: The string to check.
+ *
+ * Check whether @string is a valid D-Bus error name.
+ *
+ * This function returns the same result as g_dbus_is_interface_name(),
+ * because D-Bus error names are defined to have exactly the
+ * same syntax as interface names.
+ *
+ * Returns: %TRUE if valid, %FALSE otherwise.
+ * Since: 2.70
+ */
+
+
+/**
  * g_dbus_is_guid:
  * @string: The string to check.
  *
  * Checks if @string is a D-Bus GUID.
  *
- * See the D-Bus specification regarding what strings are valid D-Bus
- * GUID (for example, D-Bus GUIDs are not RFC-4122 compliant).
+ * See the documentation for g_dbus_generate_guid() for more information about
+ * the format of a GUID.
  *
- * Returns: %TRUE if @string is a guid, %FALSE otherwise.
+ * Returns: %TRUE if @string is a GUID, %FALSE otherwise.
  * Since: 2.26
  */
 
@@ -17610,7 +17870,9 @@
  *
  * Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field.
  *
- * Returns: The value.
+ * This will always be non-%NULL, but may be an empty string.
+ *
+ * Returns: (not nullable): The value.
  * Since: 2.26
  */
 
@@ -17796,7 +18058,7 @@
  *   fd 12: dev=0:10,mode=020620,ino=5,uid=500,gid=5,rdev=136:2,size=0,atime=1273085037,mtime=1273085851,ctime=1272982635
  * ]|
  *
- * Returns: A string that should be freed with g_free().
+ * Returns: (not nullable): A string that should be freed with g_free().
  * Since: 2.26
  */
 
@@ -18035,7 +18297,7 @@
  * If @info is statically allocated does nothing. Otherwise increases
  * the reference count.
  *
- * Returns: The same @info.
+ * Returns: (not nullable): The same @info.
  * Since: 2.26
  */
 
@@ -18423,7 +18685,7 @@
  * If @info is statically allocated does nothing. Otherwise increases
  * the reference count.
  *
- * Returns: The same @info.
+ * Returns: (not nullable): The same @info.
  * Since: 2.26
  */
 
@@ -18671,7 +18933,7 @@
  * Gets the interface proxy for @interface_name at @object_path, if
  * any.
  *
- * Returns: (transfer full): A #GDBusInterface instance or %NULL. Free
+ * Returns: (transfer full) (nullable): A #GDBusInterface instance or %NULL. Free
  *   with g_object_unref().
  * Since: 2.30
  */
@@ -18684,7 +18946,7 @@
  *
  * Gets the #GDBusObjectProxy at @object_path, if any.
  *
- * Returns: (transfer full): A #GDBusObject or %NULL. Free with
+ * Returns: (transfer full) (nullable): A #GDBusObject or %NULL. Free with
  *   g_object_unref().
  * Since: 2.30
  */
@@ -18755,7 +19017,7 @@
  *
  * Gets the #GDBusConnection used by @manager.
  *
- * Returns: (transfer full): A #GDBusConnection object or %NULL if
+ * Returns: (transfer full) (nullable): A #GDBusConnection object or %NULL if
  *   @manager isn't exported on a connection. The returned object should
  *   be freed with g_object_unref().
  * Since: 2.30
@@ -18925,7 +19187,7 @@
  * If @info is statically allocated does nothing. Otherwise increases
  * the reference count.
  *
- * Returns: The same @info.
+ * Returns: (not nullable): The same @info.
  * Since: 2.26
  */
 
@@ -19169,7 +19431,7 @@
  *
  * Gets the connection @proxy is for.
  *
- * Returns: (transfer none): A #GDBusConnection owned by @proxy. Do not free.
+ * Returns: (transfer none) (not nullable): A #GDBusConnection owned by @proxy. Do not free.
  * Since: 2.26
  */
 
@@ -19220,7 +19482,7 @@
  *
  * Gets the D-Bus interface name @proxy is for.
  *
- * Returns: A string owned by @proxy. Do not free.
+ * Returns: (not nullable): A string owned by @proxy. Do not free.
  * Since: 2.26
  */
 
@@ -19231,7 +19493,11 @@
  *
  * Gets the name that @proxy was constructed for.
  *
- * Returns: A string owned by @proxy. Do not free.
+ * When connected to a message bus, this will usually be non-%NULL.
+ * However, it may be %NULL for a proxy that communicates using a peer-to-peer
+ * pattern.
+ *
+ * Returns: (nullable): A string owned by @proxy. Do not free.
  * Since: 2.26
  */
 
@@ -19257,7 +19523,7 @@
  *
  * Gets the object path @proxy is for.
  *
- * Returns: A string owned by @proxy. Do not free.
+ * Returns: (not nullable): A string owned by @proxy. Do not free.
  * Since: 2.26
  */
 
@@ -19495,7 +19761,9 @@
  * [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses)
  * string that can be used by clients to connect to @server.
  *
- * Returns: A D-Bus address string. Do not free, the string is owned
+ * This is valid and non-empty if initializing the #GDBusServer succeeded.
+ *
+ * Returns: (not nullable): A D-Bus address string. Do not free, the string is owned
  * by @server.
  * Since: 2.26
  */
@@ -19516,9 +19784,9 @@
  * g_dbus_server_get_guid:
  * @server: A #GDBusServer.
  *
- * Gets the GUID for @server.
+ * Gets the GUID for @server, as provided to g_dbus_server_new_sync().
  *
- * Returns: A D-Bus GUID. Do not free this string, it is owned by @server.
+ * Returns: (not nullable): A D-Bus GUID. Do not free this string, it is owned by @server.
  * Since: 2.26
  */
 
@@ -19597,7 +19865,7 @@
  * If @info is statically allocated does nothing. Otherwise increases
  * the reference count.
  *
- * Returns: The same @info.
+ * Returns: (not nullable): The same @info.
  * Since: 2.26
  */
 
@@ -20629,6 +20897,24 @@
 
 
 /**
+ * g_dtls_connection_get_ciphersuite_name:
+ * @conn: a #GDTlsConnection
+ *
+ * Returns the name of the current DTLS ciphersuite, or %NULL if the
+ * connection has not handshaked or has been closed. Beware that the TLS
+ * backend may use any of multiple different naming conventions, because
+ * OpenSSL and GnuTLS have their own ciphersuite naming conventions that
+ * are different from each other and different from the standard, IANA-
+ * registered ciphersuite names. The ciphersuite name is intended to be
+ * displayed to the user for informative purposes only, and parsing it
+ * is not recommended.
+ *
+ * Returns: (nullable): The name of the current DTLS ciphersuite, or %NULL
+ * Since: 2.70
+ */
+
+
+/**
  * g_dtls_connection_get_database:
  * @conn: a #GDtlsConnection
  *
@@ -20697,6 +20983,20 @@
 
 
 /**
+ * g_dtls_connection_get_protocol_version:
+ * @conn: a #GDTlsConnection
+ *
+ * Returns the current DTLS protocol version, which may be
+ * %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or
+ * has been closed, or if the TLS backend has implemented a protocol version
+ * that is not a recognized #GTlsProtocolVersion.
+ *
+ * Returns: The current DTLS protocol version
+ * Since: 2.70
+ */
+
+
+/**
  * g_dtls_connection_get_rehandshake_mode:
  * @conn: a #GDtlsConnection
  *
@@ -22541,6 +22841,22 @@
 
 
 /**
+ * g_file_info_get_access_date_time:
+ * @info: a #GFileInfo.
+ *
+ * Gets the access time of the current @info and returns it as a
+ * #GDateTime.
+ *
+ * This requires the %G_FILE_ATTRIBUTE_TIME_ACCESS attribute. If
+ * %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC is provided, the resulting #GDateTime
+ * will have microsecond precision.
+ *
+ * Returns: (transfer full) (nullable): access time, or %NULL if unknown
+ * Since: 2.70
+ */
+
+
+/**
  * g_file_info_get_attribute_as_string:
  * @info: a #GFileInfo.
  * @attribute: a file attribute key.
@@ -22724,6 +23040,22 @@
 
 
 /**
+ * g_file_info_get_creation_date_time:
+ * @info: a #GFileInfo.
+ *
+ * Gets the creation time of the current @info and returns it as a
+ * #GDateTime.
+ *
+ * This requires the %G_FILE_ATTRIBUTE_TIME_CREATED attribute. If
+ * %G_FILE_ATTRIBUTE_TIME_CREATED_USEC is provided, the resulting #GDateTime
+ * will have microsecond precision.
+ *
+ * Returns: (transfer full) (nullable): creation time, or %NULL if unknown
+ * Since: 2.70
+ */
+
+
+/**
  * g_file_info_get_deletion_date:
  * @info: a #GFileInfo.
  *
@@ -22960,6 +23292,19 @@
 
 
 /**
+ * g_file_info_set_access_date_time:
+ * @info: a #GFileInfo.
+ * @atime: (not nullable): a #GDateTime.
+ *
+ * Sets the %G_FILE_ATTRIBUTE_TIME_ACCESS and
+ * %G_FILE_ATTRIBUTE_TIME_ACCESS_USEC attributes in the file info to the
+ * given date/time value.
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * g_file_info_set_attribute:
  * @info: a #GFileInfo.
  * @attribute: a file attribute key.
@@ -23111,6 +23456,19 @@
 
 
 /**
+ * g_file_info_set_creation_date_time:
+ * @info: a #GFileInfo.
+ * @creation_time: (not nullable): a #GDateTime.
+ *
+ * Sets the %G_FILE_ATTRIBUTE_TIME_CREATED and
+ * %G_FILE_ATTRIBUTE_TIME_CREATED_USEC attributes in the file info to the
+ * given date/time value.
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * g_file_info_set_display_name:
  * @info: a #GFileInfo.
  * @display_name: a string containing a display name.
@@ -26357,7 +26715,7 @@
  * @stream: a #GInputStream.
  * @buffer: (array length=count) (element-type guint8) (out caller-allocates):
  *     a buffer to read data into (which should be at least count bytes long).
- * @count: the number of bytes that will be read from the stream
+ * @count: (in): the number of bytes that will be read from the stream
  * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
  * @error: location to store the error occurring, or %NULL to ignore
  *
@@ -26392,7 +26750,7 @@
  * @stream: a #GInputStream.
  * @buffer: (array length=count) (element-type guint8) (out caller-allocates):
  *     a buffer to read data into (which should be at least count bytes long).
- * @count: the number of bytes that will be read from the stream
+ * @count: (in): the number of bytes that will be read from the stream
  * @bytes_read: (out): location to store the number of bytes that was read from the stream
  * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
  * @error: location to store the error occurring, or %NULL to ignore
@@ -26426,7 +26784,7 @@
  * @stream: A #GInputStream
  * @buffer: (array length=count) (element-type guint8) (out caller-allocates):
  *     a buffer to read data into (which should be at least count bytes long)
- * @count: the number of bytes that will be read from the stream
+ * @count: (in): the number of bytes that will be read from the stream
  * @io_priority: the [I/O priority][io-priority] of the request
  * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore
  * @callback: (scope async): callback to call when the request is satisfied
@@ -26474,7 +26832,7 @@
  * @stream: A #GInputStream.
  * @buffer: (array length=count) (element-type guint8) (out caller-allocates):
  *     a buffer to read data into (which should be at least count bytes long).
- * @count: the number of bytes that will be read from the stream
+ * @count: (in): the number of bytes that will be read from the stream
  * @io_priority: the [I/O priority][io-priority]
  * of the request.
  * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
@@ -29937,6 +30295,22 @@
 
 
 /**
+ * g_notification_set_category:
+ * @notification: a #GNotification
+ * @category: (nullable): the category for @notification, or %NULL for no category
+ *
+ * Sets the type of @notification to @category. Categories have a main
+ * type like `email`, `im` or `device` and can have a detail separated
+ * by a `.`, e.g. `im.received` or `email.arrived`. Setting the category
+ * helps the notification server to select proper feedback to the user.
+ *
+ * Standard categories are [listed in the specification](https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html).
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * g_notification_set_default_action:
  * @notification: a #GNotification
  * @detailed_action: a detailed action name
@@ -31019,9 +31393,9 @@
 /**
  * g_pollable_input_stream_read_nonblocking: (virtual read_nonblocking)
  * @stream: a #GPollableInputStream
- * @buffer: (array length=count) (element-type guint8): a buffer to
- *     read data into (which should be at least @count bytes long).
- * @count: the number of bytes you want to read
+ * @buffer: (array length=count) (element-type guint8) (out caller-allocates): a
+ *     buffer to read data into (which should be at least @count bytes long).
+ * @count: (in): the number of bytes you want to read
  * @cancellable: (nullable): a #GCancellable, or %NULL
  * @error: #GError for error reporting, or %NULL to ignore.
  *
@@ -31284,6 +31658,31 @@
 
 
 /**
+ * g_power_profile_monitor_dup_default:
+ *
+ * Gets a reference to the default #GPowerProfileMonitor for the system.
+ *
+ * Returns: (not nullable) (transfer full): a new reference to the default #GPowerProfileMonitor
+ * Since: 2.70
+ */
+
+
+/**
+ * g_power_profile_monitor_get_power_saver_enabled:
+ * @monitor: a #GPowerProfileMonitor
+ *
+ * Gets whether the system is in “Power Saver” mode.
+ *
+ * You are expected to listen to the
+ * #GPowerProfileMonitor::notify::power-saver-enabled signal to know when the profile has
+ * changed.
+ *
+ * Returns: Whether the system is in “Power Saver” mode.
+ * Since: 2.70
+ */
+
+
+/**
  * g_property_action_new:
  * @name: the name of the action to create
  * @object: (type GObject.Object): the object that has the property
@@ -32350,7 +32749,8 @@
  *
  * Tells the current position within the stream.
  *
- * Returns: the offset from the beginning of the buffer.
+ * Returns: the (positive or zero) offset from the beginning of the
+ * buffer, zero if the target is not seekable.
  */
 
 
@@ -36277,7 +36677,7 @@
  * This is the asynchronous version of g_socket_listener_accept().
  *
  * When the operation is finished @callback will be
- * called. You can then call g_socket_listener_accept_socket()
+ * called. You can then call g_socket_listener_accept_finish()
  * to get the result of the operation.
  *
  * Since: 2.22
@@ -37655,7 +38055,7 @@
  *
  * This value has no particular meaning, but it can be used with the
  * macros defined by the system headers such as WIFEXITED.  It can also
- * be used with g_spawn_check_exit_status().
+ * be used with g_spawn_check_wait_status().
  *
  * It is more likely that you want to use g_subprocess_get_if_exited()
  * followed by g_subprocess_get_exit_status().
@@ -38215,7 +38615,7 @@
  * @cancellable: a #GCancellable
  * @error: a #GError
  *
- * Combines g_subprocess_wait() with g_spawn_check_exit_status().
+ * Combines g_subprocess_wait() with g_spawn_check_wait_status().
  *
  * Returns: %TRUE on success, %FALSE if process exited abnormally, or
  * @cancellable was cancelled
@@ -38230,7 +38630,7 @@
  * @callback: a #GAsyncReadyCallback to call when the operation is complete
  * @user_data: user_data for @callback
  *
- * Combines g_subprocess_wait_async() with g_spawn_check_exit_status().
+ * Combines g_subprocess_wait_async() with g_spawn_check_wait_status().
  *
  * This is the asynchronous version of g_subprocess_wait_check().
  *
@@ -38730,9 +39130,9 @@
  *
  * Although GLib currently rate-limits the tasks queued via
  * g_task_run_in_thread(), you should not assume that it will always
- * do this. If you have a very large number of tasks to run, but don't
- * want them to all run at once, you should only queue a limited
- * number of them at a time.
+ * do this. If you have a very large number of tasks to run (several tens of
+ * tasks), but don't want them to all run at once, you should only queue a
+ * limited number of them (around ten) at a time.
  *
  * Since: 2.36
  */
@@ -39302,6 +39702,30 @@
 
 
 /**
+ * g_tls_certificate_get_dns_names:
+ * @cert: a #GTlsCertificate
+ *
+ * Gets the value of #GTlsCertificate:dns-names.
+ *
+ * Returns: (nullable) (element-type GBytes) (transfer container): A #GPtrArray of
+ * #GBytes elements, or %NULL if it's not available.
+ * Since: 2.70
+ */
+
+
+/**
+ * g_tls_certificate_get_ip_addresses:
+ * @cert: a #GTlsCertificate
+ *
+ * Gets the value of #GTlsCertificate:ip-addresses.
+ *
+ * Returns: (nullable) (element-type GInetAddress) (transfer container): A #GPtrArray
+ * of #GInetAddress elements, or %NULL if it's not available.
+ * Since: 2.70
+ */
+
+
+/**
  * g_tls_certificate_get_issuer:
  * @cert: a #GTlsCertificate
  *
@@ -39315,6 +39739,50 @@
 
 
 /**
+ * g_tls_certificate_get_issuer_name:
+ * @cert: a #GTlsCertificate
+ *
+ * Returns the issuer name from the certificate.
+ *
+ * Returns: (nullable) (transfer full): The issuer name, or %NULL if it's not available.
+ * Since: 2.70
+ */
+
+
+/**
+ * g_tls_certificate_get_not_valid_after:
+ * @cert: a #GTlsCertificate
+ *
+ * Returns the time at which the certificate became or will become invalid.
+ *
+ * Returns: (nullable) (transfer full): The not-valid-after date, or %NULL if it's not available.
+ * Since: 2.70
+ */
+
+
+/**
+ * g_tls_certificate_get_not_valid_before:
+ * @cert: a #GTlsCertificate
+ *
+ * Returns the time at which the certificate became or will become valid.
+ *
+ * Returns: (nullable) (transfer full): The not-valid-before date, or %NULL if it's not available.
+ * Since: 2.70
+ */
+
+
+/**
+ * g_tls_certificate_get_subject_name:
+ * @cert: a #GTlsCertificate
+ *
+ * Returns the subject name from the certificate.
+ *
+ * Returns: (nullable) (transfer full): The subject name, or %NULL if it's not available.
+ * Since: 2.70
+ */
+
+
+/**
  * g_tls_certificate_is_same:
  * @cert_one: first certificate to compare
  * @cert_two: second certificate to compare
@@ -39432,13 +39900,14 @@
  * @private_key_pkcs11_uri: (nullable): A PKCS \#11 URI
  * @error: #GError for error reporting, or %NULL to ignore.
  *
- * Creates a #GTlsCertificate from a PKCS \#11 URI.
+ * Creates a #GTlsCertificate from a
+ * [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) URI.
  *
  * An example @pkcs11_uri would be `pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01`
  *
  * Where the token’s layout is:
  *
- * ```
+ * |[
  * Object 0:
  *   URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=private%20key;type=private
  *   Type: Private key (RSA-2048)
@@ -39448,7 +39917,7 @@
  *   URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=Certificate%20for%20Authentication;type=cert
  *   Type: X.509 Certificate (RSA-2048)
  *   ID: 01
- * ```
+ * ]|
  *
  * In this case the certificate and private key would both be detected and used as expected.
  * @pkcs_uri may also just reference an X.509 certificate object and then optionally
@@ -39487,6 +39956,13 @@
  * (All other #GTlsCertificateFlags values will always be set or unset
  * as appropriate.)
  *
+ * Because TLS session context is not used, #GTlsCertificate may not
+ * perform as many checks on the certificates as #GTlsConnection would.
+ * For example, certificate constraints cannot be honored, and some
+ * revocation checks cannot be performed. The best way to verify TLS
+ * certificates used by a TLS connection is to let #GTlsConnection
+ * handle the verification.
+ *
  * Returns: the appropriate #GTlsCertificateFlags
  * Since: 2.28
  */
@@ -39719,6 +40195,24 @@
 
 
 /**
+ * g_tls_connection_get_ciphersuite_name:
+ * @conn: a #GTlsConnection
+ *
+ * Returns the name of the current TLS ciphersuite, or %NULL if the
+ * connection has not handshaked or has been closed. Beware that the TLS
+ * backend may use any of multiple different naming conventions, because
+ * OpenSSL and GnuTLS have their own ciphersuite naming conventions that
+ * are different from each other and different from the standard, IANA-
+ * registered ciphersuite names. The ciphersuite name is intended to be
+ * displayed to the user for informative purposes only, and parsing it
+ * is not recommended.
+ *
+ * Returns: (nullable): The name of the current TLS ciphersuite, or %NULL
+ * Since: 2.70
+ */
+
+
+/**
  * g_tls_connection_get_database:
  * @conn: a #GTlsConnection
  *
@@ -39787,6 +40281,20 @@
 
 
 /**
+ * g_tls_connection_get_protocol_version:
+ * @conn: a #GTlsConnection
+ *
+ * Returns the current TLS protocol version, which may be
+ * %G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or
+ * has been closed, or if the TLS backend has implemented a protocol version
+ * that is not a recognized #GTlsProtocolVersion.
+ *
+ * Returns: The current TLS protocol version
+ * Since: 2.70
+ */
+
+
+/**
  * g_tls_connection_get_rehandshake_mode:
  * @conn: a #GTlsConnection
  *
@@ -40146,14 +40654,26 @@
  * @cancellable: (nullable): a #GCancellable, or %NULL
  * @error: (nullable): a #GError, or %NULL
  *
- * Look up the issuer of @certificate in the database.
- *
- * The #GTlsCertificate:issuer property
- * of @certificate is not modified, and the two certificates are not hooked
- * into a chain.
- *
- * This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform
- * the lookup operation asynchronously.
+ * Look up the issuer of @certificate in the database. The
+ * #GTlsCertificate:issuer property of @certificate is not modified, and
+ * the two certificates are not hooked into a chain.
+ *
+ * This function can block. Use g_tls_database_lookup_certificate_issuer_async()
+ * to perform the lookup operation asynchronously.
+ *
+ * Beware this function cannot be used to build certification paths. The
+ * issuer certificate returned by this function may not be the same as
+ * the certificate that would actually be used to construct a valid
+ * certification path during certificate verification.
+ * [RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains
+ * why an issuer certificate cannot be naively assumed to be part of the
+ * the certification path (though GLib's TLS backends may not follow the
+ * path building strategies outlined in this RFC). Due to the complexity
+ * of certification path building, GLib does not provide any way to know
+ * which certification path will actually be used when verifying a TLS
+ * certificate. Accordingly, this function cannot be used to make
+ * security-related decisions. Only GLib itself should make security
+ * decisions about TLS certificates.
  *
  * Returns: (transfer full): a newly allocated issuer #GTlsCertificate,
  * or %NULL. Use g_object_unref() to release the certificate.
@@ -40260,15 +40780,11 @@
  * @cancellable: (nullable): a #GCancellable, or %NULL
  * @error: (nullable): a #GError, or %NULL
  *
- * Determines the validity of a certificate chain after looking up and
- * adding any missing certificates to the chain.
+ * Determines the validity of a certificate chain, outside the context
+ * of a TLS session.
  *
  * @chain is a chain of #GTlsCertificate objects each pointing to the next
- * certificate in the chain by its #GTlsCertificate:issuer property. The chain may initially
- * consist of one or more certificates. After the verification process is
- * complete, @chain may be modified by adding missing certificates, or removing
- * extra certificates. If a certificate anchor was found, then it is added to
- * the @chain.
+ * certificate in the chain by its #GTlsCertificate:issuer property.
  *
  * @purpose describes the purpose (or usage) for which the certificate
  * is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER
@@ -40295,8 +40811,27 @@
  * accordingly. @error is not set when @chain is successfully analyzed
  * but found to be invalid.
  *
- * This function can block, use g_tls_database_verify_chain_async() to perform
- * the verification operation asynchronously.
+ * Prior to GLib 2.48, GLib's default TLS backend modified @chain to
+ * represent the certification path built by #GTlsDatabase during
+ * certificate verification by adjusting the #GTlsCertificate:issuer
+ * property of each certificate in @chain. Since GLib 2.48, this no
+ * longer occurs, so you cannot rely on #GTlsCertificate:issuer to
+ * represent the actual certification path used during certificate
+ * verification.
+ *
+ * Because TLS session context is not used, #GTlsDatabase may not
+ * perform as many checks on the certificates as #GTlsConnection would.
+ * For example, certificate constraints cannot be honored, and some
+ * revocation checks cannot be performed. The best way to verify TLS
+ * certificates used by a TLS connection is to let #GTlsConnection
+ * handle the verification.
+ *
+ * The TLS backend may attempt to look up and add missing certificates
+ * to the chain. Since GLib 2.70, this may involve HTTP requests to
+ * download missing certificates.
+ *
+ * This function can block. Use g_tls_database_verify_chain_async() to
+ * perform the verification operation asynchronously.
  *
  * Returns: the appropriate #GTlsCertificateFlags which represents the
  * result of verification.
@@ -40612,9 +41147,9 @@
 
 
 /**
- * g_tls_password_get_value:
+ * g_tls_password_get_value: (virtual get_value)
  * @password: a #GTlsPassword object
- * @length: (nullable): location to place the length of the password.
+ * @length: (optional): location to place the length of the password.
  *
  * Get the password value. If @length is not %NULL then it will be
  * filled in with the length of the password value. (Note that the
@@ -40622,7 +41157,7 @@
  * for @length in contexts where you know the password will have a
  * certain fixed length.)
  *
- * Returns: The password value (owned by the password object).
+ * Returns: (array length=length): The password value (owned by the password object).
  * Since: 2.30
  */
 
@@ -41296,7 +41831,9 @@
  * If more mounts have the same mount path, the last matching mount
  * is returned.
  *
- * Returns: (transfer full): a #GUnixMountEntry.
+ * This will return %NULL if there is no mount point at @mount_path.
+ *
+ * Returns: (transfer full) (nullable): a #GUnixMountEntry.
  */
 
 
@@ -41335,7 +41872,10 @@
  * If more mounts have the same mount path, the last matching mount
  * is returned.
  *
- * Returns: (transfer full): a #GUnixMountEntry.
+ * This will return %NULL if looking up the mount entry fails, if
+ * @file_path doesn’t exist or there is an I/O error.
+ *
+ * Returns: (transfer full) (nullable): a #GUnixMountEntry.
  * Since: 2.52
  */
 
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 80bc0d71..5ea15d63 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -79,9 +79,9 @@
 /**
  * GAsyncQueue:
  *
- * The GAsyncQueue struct is an opaque data structure which represents
- * an asynchronous queue. It should only be accessed through the
- * g_async_queue_* functions.
+ * An opaque data structure which represents an asynchronous queue.
+ *
+ * It should only be accessed through the `g_async_queue_*` functions.
  */
 
 
@@ -232,9 +232,9 @@
 /**
  * GData:
  *
- * The #GData struct is an opaque data structure to represent a
- * [Keyed Data List][glib-Keyed-Data-Lists]. It should only be
- * accessed via the following functions.
+ * An opaque data structure that represents a keyed data list.
+ *
+ * See also: [Keyed data lists][glib-Keyed-Data-Lists].
  */
 
 
@@ -256,15 +256,15 @@
  * @julian: this bit is set if @julian_days is valid
  * @dmy: this is set if @day, @month and @year are valid
  * @day: the day of the day-month-year representation of the date,
- *     as a number between 1 and 31
+ *   as a number between 1 and 31
  * @month: the day of the day-month-year representation of the date,
- *     as a number between 1 and 12
+ *   as a number between 1 and 12
  * @year: the day of the day-month-year representation of the date
  *
  * Represents a day between January 1, Year 1 and a few thousand years in
  * the future. None of its members should be accessed directly.
  *
- * If the #GDate-struct is obtained from g_date_new(), it will be safe
+ * If the `GDate` is obtained from g_date_new(), it will be safe
  * to mutate but invalid and thus not safe for calendrical computations.
  *
  * If it's declared on the stack, it will contain garbage so must be
@@ -290,7 +290,8 @@
  * GDateDay:
  *
  * Integer representing a day of the month; between 1 and 31.
- * #G_DATE_BAD_DAY represents an invalid day of the month.
+ *
+ * The %G_DATE_BAD_DAY value represents an invalid day of the month.
  */
 
 
@@ -310,8 +311,8 @@
  * @G_DATE_NOVEMBER: November
  * @G_DATE_DECEMBER: December
  *
- * Enumeration representing a month; values are #G_DATE_JANUARY,
- * #G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value.
+ * Enumeration representing a month; values are %G_DATE_JANUARY,
+ * %G_DATE_FEBRUARY, etc. %G_DATE_BAD_MONTH is the invalid value.
  */
 
 
@@ -334,9 +335,13 @@
 /**
  * GDateYear:
  *
- * Integer representing a year; #G_DATE_BAD_YEAR is the invalid
- * value. The year must be 1 or higher; negative (BC) years are not
- * allowed. The year is represented with four digits.
+ * Integer type representing a year.
+ *
+ * The %G_DATE_BAD_YEAR value is the invalid value. The year
+ * must be 1 or higher; negative ([BCE](https://en.wikipedia.org/wiki/Common_Era))
+ * years are not allowed.
+ *
+ * The year is represented with four digits.
  */
 
 
@@ -1083,7 +1088,7 @@
 /**
  * GKeyFileError:
  * @G_KEY_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in
- *     an unknown encoding
+ *   an unknown encoding
  * @G_KEY_FILE_ERROR_PARSE: document was ill-formed
  * @G_KEY_FILE_ERROR_NOT_FOUND: the file was not found
  * @G_KEY_FILE_ERROR_KEY_NOT_FOUND: a requested key was not found
@@ -1098,13 +1103,13 @@
  * GKeyFileFlags:
  * @G_KEY_FILE_NONE: No flags, default behaviour
  * @G_KEY_FILE_KEEP_COMMENTS: Use this flag if you plan to write the
- *     (possibly modified) contents of the key file back to a file;
- *     otherwise all comments will be lost when the key file is
- *     written back.
+ *   (possibly modified) contents of the key file back to a file;
+ *   otherwise all comments will be lost when the key file is
+ *   written back.
  * @G_KEY_FILE_KEEP_TRANSLATIONS: Use this flag if you plan to write the
- *     (possibly modified) contents of the key file back to a file;
- *     otherwise only the translations for the current language will be
- *     written back.
+ *   (possibly modified) contents of the key file back to a file;
+ *   otherwise only the translations for the current language will be
+ *   written back.
  *
  * Flags which influence the parsing.
  */
@@ -2062,7 +2067,9 @@
  *
  * Simply a replacement for `time_t`. It has been deprecated
  * since it is not equivalent to `time_t` on 64-bit platforms
- * with a 64-bit `time_t`. Unrelated to #GTimer.
+ * with a 64-bit `time_t`.
+ *
+ * Unrelated to #GTimer.
  *
  * Note that #GTime is defined to always be a 32-bit integer,
  * unlike `time_t` which may be 64-bit on some systems. Therefore,
@@ -2071,6 +2078,7 @@
  * function.
  *
  * Instead, do the following:
+ *
  * |[<!-- language="C" -->
  * time_t ttime;
  * GTime gtime;
@@ -2090,7 +2098,8 @@
  * @tv_usec: microseconds
  *
  * Represents a precise time, with seconds and microseconds.
- * Similar to the struct timeval returned by the gettimeofday()
+ *
+ * Similar to the struct timeval returned by the `gettimeofday()`
  * UNIX system call.
  *
  * GLib is attempting to unify around the use of 64-bit integers to
@@ -3623,7 +3632,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_ACTIONS:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string list
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string list
  * giving the available application actions.
  *
  * Since: 2.38
@@ -3633,7 +3642,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_CATEGORIES:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list
  * of strings giving the categories in which the desktop entry
  * should be shown in a menu.
  *
@@ -3644,7 +3653,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_COMMENT:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
  * string giving the tooltip for the desktop entry.
  *
  * Since: 2.14
@@ -3654,8 +3663,8 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean set to true
- * if the application is D-Bus activatable.
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
+ * set to true if the application is D-Bus activatable.
  *
  * Since: 2.38
  */
@@ -3664,7 +3673,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_EXEC:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
  * giving the command line to execute. It is only valid for desktop
  * entries with the `Application` type.
  *
@@ -3675,7 +3684,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
  * string giving the generic name of the desktop entry.
  *
  * Since: 2.14
@@ -3685,7 +3694,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_HIDDEN:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
  * stating whether the desktop entry has been deleted by the user.
  *
  * Since: 2.14
@@ -3695,7 +3704,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_ICON:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
  * string giving the name of the icon to be displayed for the desktop
  * entry.
  *
@@ -3706,7 +3715,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_MIME_TYPE:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list
  * of strings giving the MIME types supported by this desktop entry.
  *
  * Since: 2.14
@@ -3716,7 +3725,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_NAME:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
  * string giving the specific name of the desktop entry.
  *
  * Since: 2.14
@@ -3726,7 +3735,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
  * strings identifying the environments that should not display the
  * desktop entry.
  *
@@ -3737,7 +3746,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
  * stating whether the desktop entry should be shown in menus.
  *
  * Since: 2.14
@@ -3747,7 +3756,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
  * strings identifying the environments that should display the
  * desktop entry.
  *
@@ -3758,7 +3767,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_PATH:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
  * containing the working directory to run the program in. It is only
  * valid for desktop entries with the `Application` type.
  *
@@ -3769,7 +3778,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
  * stating whether the application supports the
  * [Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec).
  *
@@ -3780,7 +3789,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is string
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is string
  * identifying the WM class or name hint of a window that the application
  * will create, which can be used to emulate Startup Notification with
  * older applications.
@@ -3792,10 +3801,10 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_TERMINAL:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
  * stating whether the program should be run in a terminal window.
- * It is only valid for desktop entries with the
- * `Application` type.
+ *
+ * It is only valid for desktop entries with the `Application` type.
  *
  * Since: 2.14
  */
@@ -3804,7 +3813,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_TRY_EXEC:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
  * giving the file name of a binary on disk used to determine if the
  * program is actually installed. It is only valid for desktop entries
  * with the `Application` type.
@@ -3816,11 +3825,12 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_TYPE:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
- * giving the type of the desktop entry. Usually
- * #G_KEY_FILE_DESKTOP_TYPE_APPLICATION,
- * #G_KEY_FILE_DESKTOP_TYPE_LINK, or
- * #G_KEY_FILE_DESKTOP_TYPE_DIRECTORY.
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
+ * giving the type of the desktop entry.
+ *
+ * Usually %G_KEY_FILE_DESKTOP_TYPE_APPLICATION,
+ * %G_KEY_FILE_DESKTOP_TYPE_LINK, or
+ * %G_KEY_FILE_DESKTOP_TYPE_DIRECTORY.
  *
  * Since: 2.14
  */
@@ -3829,7 +3839,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_URL:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
  * giving the URL to access. It is only valid for desktop entries
  * with the `Link` type.
  *
@@ -3840,7 +3850,7 @@
 /**
  * G_KEY_FILE_DESKTOP_KEY_VERSION:
  *
- * A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string
+ * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
  * giving the version of the Desktop Entry Specification used for
  * the desktop entry file.
  *
@@ -3851,7 +3861,7 @@
 /**
  * G_KEY_FILE_DESKTOP_TYPE_APPLICATION:
  *
- * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
+ * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
  * entries representing applications.
  *
  * Since: 2.14
@@ -3861,7 +3871,7 @@
 /**
  * G_KEY_FILE_DESKTOP_TYPE_DIRECTORY:
  *
- * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
+ * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
  * entries representing directories.
  *
  * Since: 2.14
@@ -3871,7 +3881,7 @@
 /**
  * G_KEY_FILE_DESKTOP_TYPE_LINK:
  *
- * The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
+ * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
  * entries representing links to documents.
  *
  * Since: 2.14
@@ -3932,7 +3942,7 @@
  * @name: the name of the lock
  *
  * Works like g_mutex_lock(), but for a lock defined with
- * #G_LOCK_DEFINE.
+ * %G_LOCK_DEFINE.
  */
 
 
@@ -3940,16 +3950,17 @@
  * G_LOCK_DEFINE:
  * @name: the name of the lock
  *
- * The #G_LOCK_ macros provide a convenient interface to #GMutex.
- * #G_LOCK_DEFINE defines a lock. It can appear in any place where
+ * The `G_LOCK_` macros provide a convenient interface to #GMutex.
+ * %G_LOCK_DEFINE defines a lock. It can appear in any place where
  * variable definitions may appear in programs, i.e. in the first block
  * of a function or outside of functions. The @name parameter will be
  * mangled to get the name of the #GMutex. This means that you
  * can use names of existing variables as the parameter - e.g. the name
  * of the variable you intend to protect with the lock. Look at our
- * give_me_next_number() example using the #G_LOCK macros:
+ * give_me_next_number() example using the `G_LOCK` macros:
+ *
+ * Here is an example for using the `G_LOCK` convenience macros:
  *
- * Here is an example for using the #G_LOCK convenience macros:
  * |[<!-- language="C" -->
  *   G_LOCK_DEFINE (current_number);
  *
@@ -3973,7 +3984,7 @@
  * G_LOCK_DEFINE_STATIC:
  * @name: the name of the lock
  *
- * This works like #G_LOCK_DEFINE, but it creates a static object.
+ * This works like %G_LOCK_DEFINE, but it creates a static object.
  */
 
 
@@ -3981,7 +3992,7 @@
  * G_LOCK_EXTERN:
  * @name: the name of the lock
  *
- * This declares a lock, that is defined with #G_LOCK_DEFINE in another
+ * This declares a lock, that is defined with %G_LOCK_DEFINE in another
  * module.
  */
 
@@ -4416,9 +4427,11 @@
 /**
  * G_SHELL_ERROR:
  *
- * Error domain for shell functions. Errors in this domain will be from
- * the #GShellError enumeration. See #GError for information on error
- * domains.
+ * Error domain for shell functions.
+ *
+ * Errors in this domain will be from the #GShellError enumeration.
+ *
+ * See #GError for information on error domains.
  */
 
 
@@ -4576,7 +4589,7 @@
  * @name: the name of the lock
  *
  * Works like g_mutex_trylock(), but for a lock defined with
- * #G_LOCK_DEFINE.
+ * %G_LOCK_DEFINE.
  *
  * Returns: %TRUE, if the lock could be locked.
  */
@@ -4617,7 +4630,7 @@
  * @name: the name of the lock
  *
  * Works like g_mutex_unlock(), but for a lock defined with
- * #G_LOCK_DEFINE.
+ * %G_LOCK_DEFINE.
  */
 
 
@@ -5236,7 +5249,7 @@
  * displaying the bookmark inside a GUI.
  *
  * Here is an example of a bookmark file:
- * [bookmarks.xbel](https://git.gnome.org/browse/glib/tree/glib/tests/bookmarks.xbel)
+ * [bookmarks.xbel](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/glib/tests/bookmarks.xbel)
  *
  * A bookmark file might contain more than one bookmark; each bookmark
  * is accessed through its URI.
@@ -5682,6 +5695,12 @@
  * function (the file being opened, or whatever - though in the
  * g_file_get_contents() case, the @message already contains a filename).
  *
+ * Since error messages may be displayed to the user, they need to be valid
+ * UTF-8 (all GTK widgets expect text to be UTF-8). Keep this in mind in
+ * particular when formatting error messages with filenames, which are in
+ * the 'filename encoding', and need to be turned into UTF-8 using
+ * g_filename_to_utf8(), g_filename_display_name() or g_utf8_make_valid().
+ *
  * Note, however, that many error messages are too technical to display to the
  * user in an application, so prefer to use g_error_matches() to categorize errors
  * from called functions, and build an appropriate error message for the context
@@ -6396,19 +6415,19 @@
  * concurrently accessed in any way from any number of threads without
  * problems.
  *
- * #GVariant is heavily optimised for dealing with data in serialised
+ * #GVariant is heavily optimised for dealing with data in serialized
  * form.  It works particularly well with data located in memory-mapped
- * files.  It can perform nearly all deserialisation operations in a
+ * files.  It can perform nearly all deserialization operations in a
  * small constant time, usually touching only a single memory page.
- * Serialised #GVariant data can also be sent over the network.
+ * Serialized #GVariant data can also be sent over the network.
  *
  * #GVariant is largely compatible with D-Bus.  Almost all types of
  * #GVariant instances can be sent over D-Bus.  See #GVariantType for
- * exceptions.  (However, #GVariant's serialisation format is not the same
- * as the serialisation format of a D-Bus message body: use #GDBusMessage,
+ * exceptions.  (However, #GVariant's serialization format is not the same
+ * as the serialization format of a D-Bus message body: use #GDBusMessage,
  * in the gio library, for those.)
  *
- * For space-efficiency, the #GVariant serialisation format does not
+ * For space-efficiency, the #GVariant serialization format does not
  * automatically include the variant's length, type or endianness,
  * which must either be implied from context (such as knowledge that a
  * particular file format always contains a little-endian
@@ -6438,14 +6457,14 @@
  * in the future.
  *
  * The memory allocated by #GVariant can be grouped into 4 broad
- * purposes: memory for serialised data, memory for the type
+ * purposes: memory for serialized data, memory for the type
  * information cache, buffer management memory and memory for the
  * #GVariant structure itself.
  *
- * ## Serialised Data Memory
+ * ## Serialized Data Memory
  *
  * This is the memory that is used for storing GVariant data in
- * serialised form.  This is what would be sent over the network or
+ * serialized form.  This is what would be sent over the network or
  * what would end up on disk, not counting any indicator of the
  * endianness, or of the length or type of the top-level variant.
  *
@@ -6479,7 +6498,7 @@
  *
  * As an example, consider a dictionary mapping strings to variants.
  * In the case that the dictionary is empty, 0 bytes are required for
- * the serialisation.
+ * the serialization.
  *
  * If we add an item "width" that maps to the int32 value of 500 then
  * we will use 4 byte to store the int32 (so 6 for the variant
@@ -6505,7 +6524,7 @@
  *
  * For each GVariant type that currently exists in the program a type
  * information structure is kept in the type information cache.  The
- * type information structure is required for rapid deserialisation.
+ * type information structure is required for rapid deserialization.
  *
  * Continuing with the above example, if a #GVariant exists with the
  * type "a{sv}" then a type information struct will exist for
@@ -6550,14 +6569,14 @@
  * ## Buffer Management Memory
  *
  * #GVariant uses an internal buffer management structure to deal
- * with the various different possible sources of serialised data
+ * with the various different possible sources of serialized data
  * that it uses.  The buffer is responsible for ensuring that the
  * correct call is made when the data is no longer in use by
  * #GVariant.  This may involve a g_free() or a g_slice_free() or
  * even g_mapped_file_unref().
  *
  * One buffer management structure is used for each chunk of
- * serialised data.  The size of the buffer management structure
+ * serialized data.  The size of the buffer management structure
  * is 4 * (void *).  On 32-bit systems, that's 16 bytes.
  *
  * ## GVariant structure
@@ -6567,7 +6586,7 @@
  *
  * #GVariant structures only exist if they are explicitly created
  * with API calls.  For example, if a #GVariant is constructed out of
- * serialised data for the example given above (with the dictionary)
+ * serialized data for the example given above (with the dictionary)
  * then although there are 9 individual values that comprise the
  * entire dictionary (two keys, two values, two variants containing
  * the values, two dictionary entries, plus the dictionary itself),
@@ -6577,8 +6596,8 @@
  * If calls are made to start accessing the other values then
  * #GVariant instances will exist for those values only for as long
  * as they are in use (ie: until you call g_variant_unref()).  The
- * type information is shared.  The serialised data and the buffer
- * management structure for that serialised data is shared by the
+ * type information is shared.  The serialized data and the buffer
+ * management structure for that serialized data is shared by the
  * child.
  *
  * ## Summary
@@ -6586,12 +6605,12 @@
  * To put the entire example together, for our dictionary mapping
  * strings to variants (with two entries, as given above), we are
  * using 91 bytes of memory for type information, 29 bytes of memory
- * for the serialised data, 16 bytes for buffer management and 24
+ * for the serialized data, 16 bytes for buffer management and 24
  * bytes for the #GVariant instance, or a total of 160 bytes, plus
  * malloc overhead.  If we were to use g_variant_get_child_value() to
  * access the two dictionary entries, we would use an additional 48
  * bytes.  If we were to have other dictionaries of the same type, we
- * would use more memory for the serialised data and buffer
+ * would use more memory for the serialized data and buffer
  * management for those dictionaries, but the type information would
  * be shared.
  */
@@ -7255,7 +7274,7 @@
  * thread-safe.
  *
  * Each event source is assigned a priority. The default priority,
- * #G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities.
+ * %G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities.
  * Values greater than 0 denote lower priorities. Events from high priority
  * sources are always processed before events from lower priority sources.
  *
@@ -7766,7 +7785,7 @@
  *   { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL },
  *   { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL },
  *   { "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL },
- *   { NULL }
+ *   G_OPTION_ENTRY_NULL
  * };
  *
  * int
@@ -8324,7 +8343,7 @@
  *                 gpointer user_data)
  * {
  *   g_message ("Child %" G_PID_FORMAT " exited %s", pid,
- *              g_spawn_check_exit_status (status, NULL) ? "normally" : "abnormally");
+ *              g_spawn_check_wait_status (status, NULL) ? "normally" : "abnormally");
  *
  *   // Free any resources associated with the child here, such as I/O channels
  *   // on its stdout and stderr FDs. If you have no code to put in the
@@ -9209,7 +9228,7 @@
  * @array: a #GArray.
  * @target: a pointer to the item to look up.
  * @compare_func: A #GCompareFunc used to locate @target.
- * @out_match_index: (optional) (out caller-allocates): return location
+ * @out_match_index: (optional) (out): return location
  *    for the index of the element, if found.
  *
  * Checks whether @target exists in @array by performing a binary
@@ -9490,6 +9509,27 @@
  * functions, @clear_func is expected to clear the contents of
  * the array element it is given, but not free the element itself.
  *
+ * |[<!-- language="C" -->
+ * typedef struct
+ * {
+ *   gchar *str;
+ *   GObject *obj;
+ * } ArrayElement;
+ *
+ * static void
+ * array_element_clear (ArrayElement *element)
+ * {
+ *   g_clear_pointer (&element->str, g_free);
+ *   g_clear_object (&element->obj);
+ * }
+ *
+ * // main code
+ * GArray *garray = g_array_new (FALSE, FALSE, sizeof (ArrayElement));
+ * g_array_set_clear_func (garray, (GDestroyNotify) array_element_clear);
+ * // assign data to the structure
+ * g_array_free (garray, TRUE);
+ * ]|
+ *
  * Since: 2.32
  */
 
@@ -9558,7 +9598,7 @@
 /**
  * g_array_steal:
  * @array: a #GArray.
- * @len: (optional) (out caller-allocates): pointer to retrieve the number of
+ * @len: (optional) (out): pointer to retrieve the number of
  *    elements of the original array
  *
  * Frees the data in the array and resets the size to zero, while
@@ -10560,7 +10600,7 @@
 
 /**
  * g_async_queue_new_full:
- * @item_free_func: function to free queue elements
+ * @item_free_func: (nullable): function to free queue elements
  *
  * Creates a new asynchronous queue and sets up a destroy notify
  * function that is used to free any remaining queue items when
@@ -11467,6 +11507,10 @@
  *
  * Atomically decreases the reference count.
  *
+ * If %TRUE is returned, the reference count reached 0. After this point, @arc
+ * is an undefined state and must be reinitialized with
+ * g_atomic_ref_count_init() to be used again.
+ *
  * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise
  * Since: 2.58
  */
@@ -11486,7 +11530,7 @@
  * g_atomic_ref_count_init:
  * @arc: the address of an atomic reference count variable
  *
- * Initializes a reference count variable.
+ * Initializes a reference count variable to 1.
  *
  * Since: 2.58
  */
@@ -11890,7 +11934,8 @@
  *
  * This function accesses @address atomically.  All other accesses to
  * @address must be atomic in order for this function to work
- * reliably.
+ * reliably. While @address has a `volatile` qualifier, this is a historical
+ * artifact and the argument passed to it should not be `volatile`.
  *
  * Since: 2.24
  */
@@ -11954,7 +11999,8 @@
  *
  * This function accesses @address atomically.  All other accesses to
  * @address must be atomic in order for this function to work
- * reliably.
+ * reliably. While @address has a `volatile` qualifier, this is a historical
+ * artifact and the argument passed to it should not be `volatile`.
  *
  * Returns: %TRUE if the lock was acquired
  * Since: 2.24
@@ -11972,7 +12018,8 @@
  *
  * This function accesses @address atomically.  All other accesses to
  * @address must be atomic in order for this function to work
- * reliably.
+ * reliably. While @address has a `volatile` qualifier, this is a historical
+ * artifact and the argument passed to it should not be `volatile`.
  *
  * Since: 2.24
  */
@@ -13175,7 +13222,7 @@
 /**
  * g_byte_array_steal:
  * @array: a #GByteArray.
- * @len: (optional) (out caller-allocates): pointer to retrieve the number of
+ * @len: (optional) (out): pointer to retrieve the number of
  *    elements of the original array
  *
  * Frees the data in the array and resets the size to zero, while
@@ -13259,6 +13306,39 @@
 
 
 /**
+ * g_bytes_get_region:
+ * @bytes: a #GBytes
+ * @element_size: a non-zero element size
+ * @offset: an offset to the start of the region within the @bytes
+ * @n_elements: the number of elements in the region
+ *
+ * Gets a pointer to a region in @bytes.
+ *
+ * The region starts at @offset many bytes from the start of the data
+ * and contains @n_elements many elements of @element_size size.
+ *
+ * @n_elements may be zero, but @element_size must always be non-zero.
+ * Ideally, @element_size is a static constant (eg: sizeof a struct).
+ *
+ * This function does careful bounds checking (including checking for
+ * arithmetic overflows) and returns a non-%NULL pointer if the
+ * specified region lies entirely within the @bytes. If the region is
+ * in some way out of range, or if an overflow has occurred, then %NULL
+ * is returned.
+ *
+ * Note: it is possible to have a valid zero-size region. In this case,
+ * the returned pointer will be equal to the base pointer of the data of
+ * @bytes, plus @offset.  This will be non-%NULL except for the case
+ * where @bytes itself was a zero-sized region.  Since it is unlikely
+ * that you will be using this function to check for a zero-sized region
+ * in a zero-sized @bytes, %NULL effectively always means "error".
+ *
+ * Returns: (nullable): the requested region, or %NULL in case of an error
+ * Since: 2.70
+ */
+
+
+/**
  * g_bytes_get_size:
  * @bytes: a #GBytes
  *
@@ -13612,16 +13692,16 @@
 /**
  * g_child_watch_add:
  * @pid: process id to watch. On POSIX the positive pid of a child
- * process. On Windows a handle for a process (which doesn't have to be
- * a child).
+ *   process. On Windows a handle for a process (which doesn't have
+ *   to be a child).
  * @function: function to call
  * @data: data to pass to @function
  *
  * Sets a function to be called when the child indicated by @pid
- * exits, at a default priority, #G_PRIORITY_DEFAULT.
+ * exits, at a default priority, %G_PRIORITY_DEFAULT.
  *
  * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes()
- * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to
+ * you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to
  * the spawn function for the child watching to work.
  *
  * Note that on platforms where #GPid must be explicitly closed
@@ -13646,7 +13726,7 @@
 /**
  * g_child_watch_add_full: (rename-to g_child_watch_add)
  * @priority: the priority of the idle source. Typically this will be in the
- *            range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
+ *   range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE.
  * @pid: process to watch. On POSIX the positive pid of a child process. On
  * Windows a handle for a process (which doesn't have to be a child).
  * @function: function to call
@@ -13657,10 +13737,10 @@
  * exits, at the priority @priority.
  *
  * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes()
- * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to
+ * you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to
  * the spawn function for the child watching to work.
  *
- * In many programs, you will want to call g_spawn_check_exit_status()
+ * In many programs, you will want to call g_spawn_check_wait_status()
  * in the callback to determine whether or not the child exited
  * successfully.
  *
@@ -14281,7 +14361,7 @@
  * @...: format string, followed by parameters to insert
  *     into the format string (as with printf())
  *
- * Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL).
+ * Logs a "critical warning" (%G_LOG_LEVEL_CRITICAL).
  *
  * Critical warnings are intended to be used in the event of an error
  * that originated in the current process (a programmer error).
@@ -16843,15 +16923,16 @@
  * @err_no: an "errno" value
  *
  * Gets a #GFileError constant based on the passed-in @err_no.
+ *
  * For example, if you pass in `EEXIST` this function returns
- * #G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably
+ * %G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably
  * assume that all #GFileError values will exist.
  *
  * Normally a #GFileError value goes into a #GError returned
  * from a function that manipulates files. So you would use
  * g_file_error_from_errno() when constructing a #GError.
  *
- * Returns: #GFileError corresponding to the given @errno
+ * Returns: #GFileError corresponding to the given @err_no
  */
 
 
@@ -17818,7 +17899,7 @@
  * This folder is used for application data
  * that is not user specific. For example, an application can store
  * a spell-check dictionary, a database of clip art, or a log file in the
- * CSIDL_COMMON_APPDATA folder. This information will not roam and is available
+ * FOLDERID_ProgramData folder. This information will not roam and is available
  * to anyone using the computer.
  *
  * The return value is cached and modifying it at runtime is not supported, as
@@ -17847,8 +17928,8 @@
  * the first elements in the list are the Application Data
  * and Documents folders for All Users. (These can be determined only
  * on Windows 2000 or later and are not present in the list on other
- * Windows versions.) See documentation for CSIDL_COMMON_APPDATA and
- * CSIDL_COMMON_DOCUMENTS.
+ * Windows versions.) See documentation for FOLDERID_ProgramData and
+ * FOLDERID_PublicDocuments.
  *
  * Then follows the "share" subfolder in the installation folder for
  * the package containing the DLL that calls this function, if it can
@@ -17913,7 +17994,7 @@
  * If `XDG_CACHE_HOME` is undefined, the directory that serves as a common
  * repository for temporary Internet files is used instead. A typical path is
  * `C:\Documents and Settings\username\Local Settings\Temporary Internet Files`.
- * See the [documentation for `CSIDL_INTERNET_CACHE`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_internet_cache).
+ * See the [documentation for `FOLDERID_InternetCache`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
  *
  * The return value is cached and modifying it at runtime is not supported, as
  * it’s not thread-safe to modify environment variables at runtime.
@@ -17938,7 +18019,7 @@
  * On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_HOME` is defined.
  * If `XDG_CONFIG_HOME` is undefined, the folder to use for local (as opposed
  * to roaming) application data is used instead. See the
- * [documentation for `CSIDL_LOCAL_APPDATA`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata).
+ * [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
  * Note that in this case on Windows it will be  the same
  * as what g_get_user_data_dir() returns.
  *
@@ -17965,7 +18046,7 @@
  * On Windows it follows XDG Base Directory Specification if `XDG_DATA_HOME`
  * is defined. If `XDG_DATA_HOME` is undefined, the folder to use for local (as
  * opposed to roaming) application data is used instead. See the
- * [documentation for `CSIDL_LOCAL_APPDATA`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata).
+ * [documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid).
  * Note that in this case on Windows it will be the same
  * as what g_get_user_config_dir() returns.
  *
@@ -18221,7 +18302,7 @@
 /**
  * g_hash_table_get_keys_as_array:
  * @hash_table: a #GHashTable
- * @length: (out): the length of the returned array
+ * @length: (out) (optional): the length of the returned array
  *
  * Retrieves every key inside @hash_table, as an array.
  *
@@ -19207,7 +19288,7 @@
  *
  * Adds a function to be called whenever there are no higher priority
  * events pending to the default main loop. The function is given the
- * default idle priority, #G_PRIORITY_DEFAULT_IDLE.  If the function
+ * default idle priority, %G_PRIORITY_DEFAULT_IDLE.  If the function
  * returns %FALSE it is automatically removed from the list of event
  * sources and will not be called again.
  *
@@ -19227,13 +19308,15 @@
 /**
  * g_idle_add_full: (rename-to g_idle_add)
  * @priority: the priority of the idle source. Typically this will be in the
- *            range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
+ *   range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE.
  * @function: function to call
  * @data: data to pass to @function
  * @notify: (nullable): function to call when the idle is removed, or %NULL
  *
  * Adds a function to be called whenever there are no higher priority
- * events pending.  If the function returns %FALSE it is automatically
+ * events pending.
+ *
+ * If the function returns %G_SOURCE_REMOVE or %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
@@ -21599,11 +21682,11 @@
 
 /**
  * g_log:
- * @log_domain: (nullable): the log domain, usually #G_LOG_DOMAIN, or %NULL
- * for the default
+ * @log_domain: (nullable): the log domain, usually %G_LOG_DOMAIN, or %NULL
+ *   for the default
  * @log_level: the log level, either from #GLogLevelFlags
- *     or a user-defined level
- * @format: the message format. See the printf() documentation
+ *   or a user-defined level
+ * @format: the message format. See the `printf()` documentation
  * @...: the parameters to insert into the format string
  *
  * Logs an error or debugging message.
@@ -21741,40 +21824,44 @@
 /**
  * g_log_set_handler:
  * @log_domain: (nullable): the log domain, or %NULL for the default ""
- *     application domain
+ *    application domain
  * @log_levels: the log levels to apply the log handler for.
- *     To handle fatal and recursive messages as well, combine
- *     the log levels with the #G_LOG_FLAG_FATAL and
- *     #G_LOG_FLAG_RECURSION bit flags.
+ *    To handle fatal and recursive messages as well, combine
+ *    the log levels with the %G_LOG_FLAG_FATAL and
+ *    %G_LOG_FLAG_RECURSION bit flags.
  * @log_func: the log handler function
  * @user_data: data passed to the log handler
  *
  * Sets the log handler for a domain and a set of log levels.
+ *
  * To handle fatal and recursive messages the @log_levels parameter
- * must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION
+ * must be combined with the %G_LOG_FLAG_FATAL and %G_LOG_FLAG_RECURSION
  * bit flags.
  *
- * Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if
+ * Note that since the %G_LOG_LEVEL_ERROR log level is always fatal, if
  * you want to set a handler for this log level you must combine it with
- * #G_LOG_FLAG_FATAL.
+ * %G_LOG_FLAG_FATAL.
  *
  * This has no effect if structured logging is enabled; see
  * [Using Structured Logging][using-structured-logging].
  *
  * Here is an example for adding a log handler for all warning messages
  * in the default domain:
+ *
  * |[<!-- language="C" -->
  * g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
  *                    | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
  * ]|
  *
  * This example adds a log handler for all critical messages from GTK+:
+ *
  * |[<!-- language="C" -->
  * g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
  *                    | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
  * ]|
  *
  * This example adds a log handler for all messages from GLib:
+ *
  * |[<!-- language="C" -->
  * g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
  *                    | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
@@ -21787,11 +21874,11 @@
 /**
  * g_log_set_handler_full: (rename-to g_log_set_handler)
  * @log_domain: (nullable): the log domain, or %NULL for the default ""
- *     application domain
+ *   application domain
  * @log_levels: the log levels to apply the log handler for.
- *     To handle fatal and recursive messages as well, combine
- *     the log levels with the #G_LOG_FLAG_FATAL and
- *     #G_LOG_FLAG_RECURSION bit flags.
+ *   To handle fatal and recursive messages as well, combine
+ *   the log levels with the %G_LOG_FLAG_FATAL and
+ *   %G_LOG_FLAG_RECURSION bit flags.
  * @log_func: the log handler function
  * @user_data: data passed to the log handler
  * @destroy: destroy notify for @user_data, or %NULL
@@ -21836,10 +21923,12 @@
  *    by the key "MESSAGE", followed by a printf()-style message format,
  *    followed by parameters to insert in the format string
  *
- * Log a message with structured data. The message will be passed through to
- * the log writer set by the application using g_log_set_writer_func(). If the
- * message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will
- * be aborted by calling G_BREAKPOINT() at the end of this function. If the log writer returns
+ * Log a message with structured data.
+ *
+ * The message will be passed through to the log writer set by the application
+ * using g_log_set_writer_func(). If the message is fatal (i.e. its log level
+ * is %G_LOG_LEVEL_ERROR), the program will be aborted by calling
+ * G_BREAKPOINT() at the end of this function. If the log writer returns
  * %G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried.
  * See the documentation for #GLogWriterFunc for information on chaining
  * writers.
@@ -21873,9 +21962,10 @@
  * Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by
  * the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(),
  * g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including
- * glib.h.
+ * `glib.h`.
  *
  * For example:
+ *
  * |[<!-- language="C" -->
  * g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,
  *                   "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e",
@@ -21896,6 +21986,7 @@
  * interpreted as a string.
  *
  * For example:
+ *
  * |[<!-- language="C" -->
  * const GLogField fields[] = {
  *   { "MESSAGE", "This is a debug message.", -1 },
@@ -22398,7 +22489,7 @@
  *
  * In any other case, an idle source is created to call @function and
  * that source is attached to @context (presumably to be run in another
- * thread).  The idle source is attached with #G_PRIORITY_DEFAULT
+ * thread).  The idle source is attached with %G_PRIORITY_DEFAULT
  * priority.  If you want a different priority, use
  * g_main_context_invoke_full().
  *
@@ -25314,7 +25405,7 @@
 
 
 /**
- * g_pattern_match:
+ * g_pattern_match: (skip)
  * @pspec: a #GPatternSpec
  * @string_length: the length of @string (in bytes, i.e. strlen(),
  *     not g_utf8_strlen())
@@ -25340,6 +25431,7 @@
  * g_utf8_strreverse() function to reverse UTF-8 encoded strings.
  *
  * Returns: %TRUE if @string matches @pspec
+ * Deprecated: 2.70: Use g_pattern_spec_match() instead
  */
 
 
@@ -25358,7 +25450,7 @@
 
 
 /**
- * g_pattern_match_string:
+ * g_pattern_match_string: (skip)
  * @pspec: a #GPatternSpec
  * @string: the UTF-8 encoded string to match
  *
@@ -25367,6 +25459,18 @@
  * g_pattern_match() instead while supplying the reversed string.
  *
  * Returns: %TRUE if @string matches @pspec
+ * Deprecated: 2.70: Use g_pattern_spec_match_string() instead
+ */
+
+
+/**
+ * g_pattern_spec_copy:
+ * @pspec: a #GPatternSpec
+ *
+ * Copies @pspec in a new #GPatternSpec.
+ *
+ * Returns: (transfer full): a copy of @pspec.
+ * Since: 2.70
  */
 
 
@@ -25391,6 +25495,51 @@
 
 
 /**
+ * g_pattern_spec_match:
+ * @pspec: a #GPatternSpec
+ * @string_length: the length of @string (in bytes, i.e. strlen(),
+ *     not g_utf8_strlen())
+ * @string: the UTF-8 encoded string to match
+ * @string_reversed: (nullable): the reverse of @string or %NULL
+ *
+ * Matches a string against a compiled pattern. Passing the correct
+ * length of the string given is mandatory. The reversed string can be
+ * omitted by passing %NULL, this is more efficient if the reversed
+ * version of the string to be matched is not at hand, as
+ * g_pattern_match() will only construct it if the compiled pattern
+ * requires reverse matches.
+ *
+ * Note that, if the user code will (possibly) match a string against a
+ * multitude of patterns containing wildcards, chances are high that
+ * some patterns will require a reversed string. In this case, it's
+ * more efficient to provide the reversed string to avoid multiple
+ * constructions thereof in the various calls to g_pattern_match().
+ *
+ * Note also that the reverse of a UTF-8 encoded string can in general
+ * not be obtained by g_strreverse(). This works only if the string
+ * does not contain any multibyte characters. GLib offers the
+ * g_utf8_strreverse() function to reverse UTF-8 encoded strings.
+ *
+ * Returns: %TRUE if @string matches @pspec
+ * Since: 2.70
+ */
+
+
+/**
+ * g_pattern_spec_match_string:
+ * @pspec: a #GPatternSpec
+ * @string: the UTF-8 encoded string to match
+ *
+ * Matches a string against a compiled pattern. If the string is to be
+ * matched against more than one pattern, consider using
+ * g_pattern_match() instead while supplying the reversed string.
+ *
+ * Returns: %TRUE if @string matches @pspec
+ * Since: 2.70
+ */
+
+
+/**
  * g_pattern_spec_new:
  * @pattern: a zero-terminated UTF-8 encoded string
  *
@@ -25411,6 +25560,9 @@
  * For portability reasons, you may only lock on the bottom 32 bits of
  * the pointer.
  *
+ * While @address has a `volatile` qualifier, this is a historical
+ * artifact and the argument passed to it should not be `volatile`.
+ *
  * Since: 2.30
  */
 
@@ -25420,12 +25572,15 @@
  * @address: (not nullable): a pointer to a #gpointer-sized value
  * @lock_bit: a bit value between 0 and 31
  *
- * This is equivalent to g_bit_trylock, but working on pointers (or
+ * This is equivalent to g_bit_trylock(), but working on pointers (or
  * other pointer-sized values).
  *
  * For portability reasons, you may only lock on the bottom 32 bits of
  * the pointer.
  *
+ * While @address has a `volatile` qualifier, this is a historical
+ * artifact and the argument passed to it should not be `volatile`.
+ *
  * Returns: %TRUE if the lock was acquired
  * Since: 2.30
  */
@@ -25442,6 +25597,9 @@
  * For portability reasons, you may only lock on the bottom 32 bits of
  * the pointer.
  *
+ * While @address has a `volatile` qualifier, this is a historical
+ * artifact and the argument passed to it should not be `volatile`.
+ *
  * Since: 2.30
  */
 
@@ -25495,6 +25653,18 @@
 
 
 /**
+ * g_prefix_error_literal:
+ * @err: (allow-none): a return location for a #GError, or %NULL
+ * @prefix: string to prefix @err with
+ *
+ * Prefixes @prefix to an existing error message. If @err or *@err is
+ * %NULL (i.e.: no error variable) then do nothing.
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * g_print:
  * @format: the message format. See the printf() documentation
  * @...: the parameters to insert into the format string
@@ -25715,7 +25885,7 @@
  * g_ptr_array_find: (skip)
  * @haystack: pointer array to be searched
  * @needle: pointer to look for
- * @index_: (optional) (out caller-allocates): return location for the index of
+ * @index_: (optional) (out): return location for the index of
  *    the element, if found
  *
  * Checks whether @needle exists in @haystack. If the element is found, %TRUE is
@@ -25738,7 +25908,7 @@
  * @equal_func: (nullable): the function to call for each element, which should
  *    return %TRUE when the desired element is found; or %NULL to use pointer
  *    equality
- * @index_: (optional) (out caller-allocates): return location for the index of
+ * @index_: (optional) (out): return location for the index of
  *    the element, if found
  *
  * Checks whether @needle exists in @haystack, using the given @equal_func.
@@ -26107,7 +26277,7 @@
 /**
  * g_ptr_array_steal:
  * @array: a #GPtrArray.
- * @len: (optional) (out caller-allocates): pointer to retrieve the number of
+ * @len: (optional) (out): pointer to retrieve the number of
  *    elements of the original array
  *
  * Frees the data in the array and resets the size to zero, while
@@ -27306,6 +27476,10 @@
  *
  * Decreases the reference count.
  *
+ * If %TRUE is returned, the reference count reached 0. After this point, @rc
+ * is an undefined state and must be reinitialized with
+ * g_ref_count_init() to be used again.
+ *
  * Returns: %TRUE if the reference count reached 0, and %FALSE otherwise
  * Since: 2.58
  */
@@ -27325,7 +27499,7 @@
  * g_ref_count_init:
  * @rc: the address of a reference count variable
  *
- * Initializes a reference count variable.
+ * Initializes a reference count variable to 1.
  *
  * Since: 2.58
  */
@@ -29366,12 +29540,16 @@
  * Parses a command line into an argument vector, in much the same way
  * the shell would, but without many of the expansions the shell would
  * perform (variable expansion, globs, operators, filename expansion,
- * etc. are not supported). The results are defined to be the same as
- * those you would get from a UNIX98 /bin/sh, as long as the input
- * contains none of the unsupported shell expansions. If the input
- * does contain such expansions, they are passed through
- * literally. Possible errors are those from the #G_SHELL_ERROR
- * domain. Free the returned vector with g_strfreev().
+ * etc. are not supported).
+ *
+ * The results are defined to be the same as those you would get from
+ * a UNIX98 `/bin/sh`, as long as the input contains none of the
+ * unsupported shell expansions. If the input does contain such expansions,
+ * they are passed through literally.
+ *
+ * Possible errors are those from the %G_SHELL_ERROR domain.
+ *
+ * Free the returned vector with g_strfreev().
  *
  * Returns: %TRUE on success, %FALSE if error set
  */
@@ -29382,13 +29560,17 @@
  * @unquoted_string: (type filename): a literal string
  *
  * Quotes a string so that the shell (/bin/sh) will interpret the
- * quoted string to mean @unquoted_string. If you pass a filename to
- * the shell, for example, you should first quote it with this
- * function.  The return value must be freed with g_free(). The
- * quoting style used is undefined (single or double quotes may be
+ * quoted string to mean @unquoted_string.
+ *
+ * If you pass a filename to the shell, for example, you should first
+ * quote it with this function.
+ *
+ * The return value must be freed with g_free().
+ *
+ * The quoting style used is undefined (single or double quotes may be
  * used).
  *
- * Returns: (type filename): quoted string
+ * Returns: (type filename) (transfer full): quoted string
  */
 
 
@@ -29397,27 +29579,33 @@
  * @quoted_string: (type filename): shell-quoted string
  * @error: error return location or NULL
  *
- * Unquotes a string as the shell (/bin/sh) would. Only handles
- * quotes; if a string contains file globs, arithmetic operators,
- * variables, backticks, redirections, or other special-to-the-shell
- * features, the result will be different from the result a real shell
- * would produce (the variables, backticks, etc. will be passed
- * through literally instead of being expanded). This function is
- * guaranteed to succeed if applied to the result of
+ * Unquotes a string as the shell (/bin/sh) would.
+ *
+ * This function only handles quotes; if a string contains file globs,
+ * arithmetic operators, variables, backticks, redirections, or other
+ * special-to-the-shell features, the result will be different from the
+ * result a real shell would produce (the variables, backticks, etc.
+ * will be passed through literally instead of being expanded).
+ *
+ * This function is guaranteed to succeed if applied to the result of
  * g_shell_quote(). If it fails, it returns %NULL and sets the
- * error. The @quoted_string need not actually contain quoted or
- * escaped text; g_shell_unquote() simply goes through the string and
- * unquotes/unescapes anything that the shell would. Both single and
- * double quotes are handled, as are escapes including escaped
- * newlines. The return value must be freed with g_free(). Possible
- * errors are in the #G_SHELL_ERROR domain.
+ * error.
+ *
+ * The @quoted_string need not actually contain quoted or escaped text;
+ * g_shell_unquote() simply goes through the string and unquotes/unescapes
+ * anything that the shell would. Both single and double quotes are
+ * handled, as are escapes including escaped newlines.
+ *
+ * The return value must be freed with g_free().
+ *
+ * Possible errors are in the %G_SHELL_ERROR domain.
  *
  * Shell quoting rules are a bit strange. Single quotes preserve the
  * literal string exactly. escape sequences are not allowed; not even
- * \' - if you want a ' in the quoted text, you have to do something
- * like 'foo'\''bar'.  Double quotes allow $, `, ", \, and newline to
- * be escaped with backslash. Otherwise double quotes preserve things
- * literally.
+ * `\'` - if you want a `'` in the quoted text, you have to do something
+ * like `'foo'\''bar'`. Double quotes allow `$`, ```, `"`, `\`, and
+ * newline to be escaped with backslash. Otherwise double quotes
+ * preserve things literally.
  *
  * Returns: (type filename): an unquoted string
  */
@@ -29464,17 +29652,19 @@
  * @block_size: the number of bytes to allocate
  *
  * Allocates a block of memory from the slice allocator.
+ *
  * The block address handed out can be expected to be aligned
- * to at least 1 * sizeof (void*),
- * though in general slices are 2 * sizeof (void*) bytes aligned,
- * if a malloc() fallback implementation is used instead,
- * the alignment may be reduced in a libc dependent fashion.
+ * to at least `1 * sizeof (void*)`, though in general slices
+ * are `2 * sizeof (void*)` bytes aligned; if a `malloc()`
+ * fallback implementation is used instead, the alignment may
+ * be reduced in a libc dependent fashion.
+ *
  * Note that the underlying slice allocation mechanism can
  * be changed with the [`G_SLICE=always-malloc`][G_SLICE]
  * environment variable.
  *
- * Returns: a pointer to the allocated memory block, which will be %NULL if and
- *    only if @mem_size is 0
+ * Returns: a pointer to the allocated memory block, which will
+ *   be %NULL if and only if @mem_size is 0
  * Since: 2.10
  */
 
@@ -29579,6 +29769,7 @@
  * @next: the field name of the next pointer in @type
  *
  * Frees a linked list of memory blocks of structure type @type.
+ *
  * The memory blocks must be equal-sized, allocated via
  * g_slice_alloc() or g_slice_alloc0() and linked together by
  * a @next pointer (similar to #GSList). The name of the
@@ -30277,6 +30468,10 @@
  *
  * This function is safe to call from any thread, regardless of which thread
  * the #GMainContext is running in.
+ *
+ * If the source is currently attached to a #GMainContext, destroying it
+ * will effectively unset the callback similar to calling g_source_set_callback().
+ * This can mean, that the data's #GDestroyNotify gets called right away.
  */
 
 
@@ -30678,6 +30873,9 @@
  * It is safe to call this function multiple times on a source which has already
  * been attached to a context. The changes will take effect for the next time
  * the source is dispatched after this call returns.
+ *
+ * Note that g_source_destroy() for a currently attached source has the effect
+ * of also unsetting the callback.
  */
 
 
@@ -30773,6 +30971,8 @@
  * the value, and changing the value will free it while the other thread
  * may be attempting to use it.
  *
+ * Also see g_source_set_static_name().
+ *
  * Since: 2.26
  */
 
@@ -30853,6 +31053,19 @@
 
 
 /**
+ * g_source_set_static_name:
+ * @source: a #GSource
+ * @name: debug name for the source
+ *
+ * A variant of g_source_set_name() that does not
+ * duplicate the @name, and can only be used with
+ * string literals.
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * g_source_unref:
  * @source: a #GSource
  *
@@ -30892,13 +31105,15 @@
  * @child_pid: (out) (optional): return location for child process reference, or %NULL
  * @error: return location for error
  *
+ * Executes a child program asynchronously.
+ *
  * See g_spawn_async_with_pipes() for a full description; this function
  * simply calls the g_spawn_async_with_pipes() without any pipes.
  *
  * You should call g_spawn_close_pid() on the returned child process
  * reference when you don't need it any more.
  *
- * If you are writing a GTK+ application, and the program you are spawning is a
+ * If you are writing a GTK application, and the program you are spawning is a
  * graphical application too, then to ensure that the spawned program opens its
  * windows on the right screen, you may want to use #GdkAppLaunchContext,
  * #GAppLaunchContext, or set the %DISPLAY environment variable.
@@ -30925,6 +31140,8 @@
  * @stderr_fd: file descriptor to use for child's stderr, or `-1`
  * @error: return location for error
  *
+ * Executes a child program asynchronously.
+ *
  * Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero,
  * so no FD assignments are used.
  *
@@ -30985,52 +31202,53 @@
  * @error: return location for error
  *
  * Executes a child program asynchronously (your program will not
- * block waiting for the child to exit). The child program is
- * specified by the only argument that must be provided, @argv.
- * @argv should be a %NULL-terminated array of strings, to be passed
- * as the argument vector for the child. The first string in @argv
- * is of course the name of the program to execute. By default, the
- * name of the program must be a full path. If @flags contains the
- * %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is
- * used to search for the executable. If @flags contains the
- * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from
- * @envp is used to search for the executable. If both the
- * %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags
- * are set, the `PATH` variable from @envp takes precedence over
- * the environment variable.
- *
- * If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not
- * used, then the program will be run from the current directory (or
- * @working_directory, if specified); this might be unexpected or even
+ * block waiting for the child to exit).
+ *
+ * The child program is specified by the only argument that must be
+ * provided, @argv. @argv should be a %NULL-terminated array of strings,
+ * to be passed as the argument vector for the child. The first string
+ * in @argv is of course the name of the program to execute. By default,
+ * the name of the program must be a full path. If @flags contains the
+ * %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is used to
+ * search for the executable. If @flags contains the
+ * %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from @envp
+ * is used to search for the executable. If both the
+ * %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags are
+ * set, the `PATH` variable from @envp takes precedence over the
+ * environment variable.
+ *
+ * If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag
+ * is not used, then the program will be run from the current directory
+ * (or @working_directory, if specified); this might be unexpected or even
  * dangerous in some cases when the current directory is world-writable.
  *
  * On Windows, note that all the string or string vector arguments to
- * this function and the other g_spawn*() functions are in UTF-8, the
+ * this function and the other `g_spawn*()` functions are in UTF-8, the
  * GLib file name encoding. Unicode characters that are not part of
  * the system codepage passed in these arguments will be correctly
  * available in the spawned program only if it uses wide character API
  * to retrieve its command line. For C programs built with Microsoft's
- * tools it is enough to make the program have a wmain() instead of
- * main(). wmain() has a wide character argument vector as parameter.
+ * tools it is enough to make the program have a `wmain()` instead of
+ * `main()`. `wmain()` has a wide character argument vector as parameter.
  *
- * At least currently, mingw doesn't support wmain(), so if you use
+ * At least currently, mingw doesn't support `wmain()`, so if you use
  * 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()
+ * On Windows the low-level child process creation API `CreateProcess()`
  * doesn't use argument vectors, but a command line. The C runtime
- * library's spawn*() family of functions (which g_spawn_async_with_pipes()
+ * library's `spawn*()` family of functions (which g_spawn_async_with_pipes()
  * eventually calls) paste the argument vector elements together into
  * a command line, and the C runtime startup code does a corresponding
  * reconstruction of an argument vector from the command line, to be
- * passed to main(). Complications arise when you have argument vector
+ * passed to `main()`. Complications arise when you have argument vector
  * elements that contain spaces or double quotes. The `spawn*()` functions
  * don't do any quoting or escaping, but on the other hand the startup
  * code does do unquoting and unescaping in order to enable receiving
  * arguments with embedded spaces or double quotes. To work around this
  * asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on
  * argument vector elements that need it before calling the C runtime
- * spawn() function.
+ * `spawn()` function.
  *
  * The returned @child_pid on Windows is a handle to the child
  * process, not its identifier. Process handles and process
@@ -31049,13 +31267,13 @@
  * free resources which may be associated with the child process. (On Unix,
  * using a child watch is equivalent to calling waitpid() or handling
  * the `SIGCHLD` signal manually. On Windows, calling g_spawn_close_pid()
- * is equivalent to calling CloseHandle() on the process handle returned
+ * is equivalent to calling `CloseHandle()` on the process handle returned
  * in @child_pid). See g_child_watch_add().
  *
  * Open UNIX file descriptors marked as `FD_CLOEXEC` will be automatically
  * closed in the child process. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that
  * other open file descriptors will be inherited by the child; otherwise all
- * descriptors except stdin/stdout/stderr will be closed before calling exec()
+ * descriptors except stdin/stdout/stderr will be closed before calling `exec()`
  * in the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an
  * absolute path, it will be looked for in the `PATH` environment
  * variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an
@@ -31096,25 +31314,25 @@
  * @child_setup and @user_data are a function and user data. On POSIX
  * platforms, the function is called in the child after GLib has
  * performed all the setup it plans to perform (including creating
- * pipes, closing file descriptors, etc.) but before calling exec().
- * That is, @child_setup is called just before calling exec() in the
+ * pipes, closing file descriptors, etc.) but before calling `exec()`.
+ * That is, @child_setup is called just before calling `exec()` in the
  * child. Obviously actions taken in this function will only affect
  * the child, not the parent.
  *
- * On Windows, there is no separate fork() and exec() functionality.
+ * On Windows, there is no separate `fork()` and `exec()` functionality.
  * Child processes are created and run with a single API call,
- * CreateProcess(). There is no sensible thing @child_setup
+ * `CreateProcess()`. There is no sensible thing @child_setup
  * could be used for on Windows so it is ignored and not called.
  *
  * If non-%NULL, @child_pid will on Unix be filled with the child's
  * process ID. You can use the process ID to send signals to the child,
- * or to use g_child_watch_add() (or waitpid()) if you specified the
+ * or to use g_child_watch_add() (or `waitpid()`) if you specified the
  * %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be
  * filled with a handle to the child process only if you specified the
  * %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child
  * process using the Win32 API, for example wait for its termination
- * with the WaitFor*() functions, or examine its exit code with
- * GetExitCodeProcess(). You should close the handle with CloseHandle()
+ * with the `WaitFor*()` functions, or examine its exit code with
+ * `GetExitCodeProcess()`. You should close the handle with `CloseHandle()`
  * or g_spawn_close_pid() when you no longer need it.
  *
  * If non-%NULL, the @stdin_pipe_out, @stdout_pipe_out, @stderr_pipe_out
@@ -31138,7 +31356,7 @@
  * @error can be %NULL to ignore errors, or non-%NULL to report errors.
  * If an error is set, the function returns %FALSE. Errors are reported
  * even if they occur in the child (for example if the executable in
- * @argv[0] is not found). Typically the `message` field of returned
+ * `@argv[0]` is not found). Typically the `message` field of returned
  * errors should be displayed to users. Possible errors are those from
  * the #G_SPAWN_ERROR domain.
  *
@@ -31149,7 +31367,7 @@
  * process reference must be closed using g_spawn_close_pid().
  *
  * On modern UNIX platforms, GLib can use an efficient process launching
- * codepath driven internally by posix_spawn(). This has the advantage of
+ * codepath driven internally by `posix_spawn()`. This has the advantage of
  * avoiding the fork-time performance costs of cloning the parent process
  * address space, and avoiding associated memory overcommit checks that are
  * not relevant in the context of immediately executing a distinct process.
@@ -31161,9 +31379,11 @@
  * 3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set
  * 4. @working_directory is %NULL
  * 5. @child_setup is %NULL
- * 6. The program is of a recognised binary format, or has a shebang. Otherwise, GLib will have to execute the program through the shell, which is not done using the optimized codepath.
+ * 6. The program is of a recognised binary format, or has a shebang.
+ *    Otherwise, GLib will have to execute the program through the
+ *    shell, which is not done using the optimized codepath.
  *
- * If you are writing a GTK+ application, and the program you are spawning is a
+ * If you are writing a GTK application, and the program you are spawning is a
  * graphical application too, then to ensure that the spawned program opens its
  * windows on the right screen, you may want to use #GdkAppLaunchContext,
  * #GAppLaunchContext, or set the `DISPLAY` environment variable.
@@ -31175,49 +31395,73 @@
 
 /**
  * g_spawn_check_exit_status:
- * @exit_status: An exit code as returned from g_spawn_sync()
+ * @wait_status: A status as returned from g_spawn_sync()
+ * @error: a #GError
+ *
+ * An old name for g_spawn_check_wait_status(), deprecated because its
+ * name is misleading.
+ *
+ * Despite the name of the function, @wait_status must be the wait status
+ * as returned by g_spawn_sync(), g_subprocess_get_status(), `waitpid()`,
+ * etc. On Unix platforms, it is incorrect for it to be the exit status
+ * as passed to `exit()` or returned by g_subprocess_get_exit_status() or
+ * `WEXITSTATUS()`.
+ *
+ * Returns: %TRUE if child exited successfully, %FALSE otherwise (and
+ *     @error will be set)
+ * Since: 2.34
+ * Deprecated: 2.70: Use g_spawn_check_wait_status() instead, and check whether your code is conflating wait and exit statuses.
+ */
+
+
+/**
+ * g_spawn_check_wait_status:
+ * @wait_status: A platform-specific wait status as returned from g_spawn_sync()
  * @error: a #GError
  *
- * Set @error if @exit_status indicates the child exited abnormally
+ * Set @error if @wait_status indicates the child exited abnormally
  * (e.g. with a nonzero exit code, or via a fatal signal).
  *
- * The g_spawn_sync() and g_child_watch_add() family of APIs return an
- * exit status for subprocesses encoded in a platform-specific way.
+ * The g_spawn_sync() and g_child_watch_add() family of APIs return the
+ * status of subprocesses encoded in a platform-specific way.
  * On Unix, this is guaranteed to be in the same format waitpid() returns,
  * and on Windows it is guaranteed to be the result of GetExitCodeProcess().
  *
  * Prior to the introduction of this function in GLib 2.34, interpreting
- * @exit_status required use of platform-specific APIs, which is problematic
+ * @wait_status required use of platform-specific APIs, which is problematic
  * for software using GLib as a cross-platform layer.
  *
  * Additionally, many programs simply want to determine whether or not
  * the child exited successfully, and either propagate a #GError or
  * print a message to standard error. In that common case, this function
  * can be used. Note that the error message in @error will contain
- * human-readable information about the exit status.
+ * human-readable information about the wait status.
  *
  * The @domain and @code of @error have special semantics in the case
  * where the process has an "exit code", as opposed to being killed by
  * a signal. On Unix, this happens if WIFEXITED() would be true of
- * @exit_status. On Windows, it is always the case.
+ * @wait_status. On Windows, it is always the case.
  *
  * The special semantics are that the actual exit code will be the
  * code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR.
  * This allows you to differentiate between different exit codes.
  *
  * If the process was terminated by some means other than an exit
- * status, the domain will be %G_SPAWN_ERROR, and the code will be
- * %G_SPAWN_ERROR_FAILED.
+ * status (for example if it was killed by a signal), the domain will be
+ * %G_SPAWN_ERROR and the code will be %G_SPAWN_ERROR_FAILED.
  *
  * This function just offers convenience; you can of course also check
  * the available platform via a macro such as %G_OS_UNIX, and use
- * WIFEXITED() and WEXITSTATUS() on @exit_status directly. Do not attempt
+ * WIFEXITED() and WEXITSTATUS() on @wait_status directly. Do not attempt
  * to scan or parse the error message string; it may be translated and/or
  * change in future versions of GLib.
  *
+ * Prior to version 2.70, g_spawn_check_exit_status() provides the same
+ * functionality, although under a misleading name.
+ *
  * Returns: %TRUE if child exited successfully, %FALSE otherwise (and
- *     @error will be set)
- * Since: 2.34
+ *   @error will be set)
+ * Since: 2.70
  */
 
 
@@ -31238,8 +31482,9 @@
  * @error: return location for errors
  *
  * A simple version of g_spawn_async() that parses a command line with
- * g_shell_parse_argv() and passes it to g_spawn_async(). Runs a
- * command line in the background. Unlike g_spawn_async(), the
+ * g_shell_parse_argv() and passes it to g_spawn_async().
+ *
+ * Runs a command line in the background. Unlike g_spawn_async(), the
  * %G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note
  * that %G_SPAWN_SEARCH_PATH can have security implications, so
  * consider using g_spawn_async() directly if appropriate. Possible
@@ -31256,21 +31501,28 @@
  * @command_line: (type filename): a command line
  * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child output
  * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child errors
- * @exit_status: (out) (optional): return location for child exit status, as returned by waitpid()
+ * @wait_status: (out) (optional): return location for child wait status, as returned by waitpid()
  * @error: return location for errors
  *
  * A simple version of g_spawn_sync() with little-used parameters
- * removed, taking a command line instead of an argument vector.  See
- * g_spawn_sync() for full details. @command_line will be parsed by
- * g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag
- * is enabled. Note that %G_SPAWN_SEARCH_PATH can have security
- * implications, so consider using g_spawn_sync() directly if
- * appropriate. Possible errors are those from g_spawn_sync() and those
+ * removed, taking a command line instead of an argument vector.
+ *
+ * See g_spawn_sync() for full details.
+ *
+ * The @command_line argument will be parsed by g_shell_parse_argv().
+ *
+ * Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag is enabled.
+ * Note that %G_SPAWN_SEARCH_PATH can have security implications, so
+ * consider using g_spawn_sync() directly if appropriate.
+ *
+ * Possible errors are those from g_spawn_sync() and those
  * from g_shell_parse_argv().
  *
- * If @exit_status is non-%NULL, the platform-specific exit status of
+ * If @wait_status is non-%NULL, the platform-specific status of
  * the child is stored there; see the documentation of
- * g_spawn_check_exit_status() for how to use and interpret this.
+ * g_spawn_check_wait_status() for how to use and interpret this.
+ * On Unix platforms, note that it is usually not equal
+ * to the integer passed to `exit()` or returned from `main()`.
  *
  * On Windows, please note the implications of g_shell_parse_argv()
  * parsing @command_line. Parsing is done according to Unix shell rules, not
@@ -31299,24 +31551,28 @@
  * @user_data: (closure): user data for @child_setup
  * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child output, or %NULL
  * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child error messages, or %NULL
- * @exit_status: (out) (optional): return location for child exit status, as returned by waitpid(), or %NULL
+ * @wait_status: (out) (optional): return location for child wait status, as returned by waitpid(), or %NULL
  * @error: return location for error, or %NULL
  *
  * Executes a child synchronously (waits for the child to exit before returning).
+ *
  * All output from the child is stored in @standard_output and @standard_error,
  * if those parameters are non-%NULL. Note that you must set the
  * %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when
  * passing %NULL for @standard_output and @standard_error.
  *
- * If @exit_status is non-%NULL, the platform-specific exit status of
+ * If @wait_status is non-%NULL, the platform-specific status of
  * the child is stored there; see the documentation of
- * g_spawn_check_exit_status() for how to use and interpret this.
+ * g_spawn_check_wait_status() for how to use and interpret this.
+ * On Unix platforms, note that it is usually not equal
+ * to the integer passed to `exit()` or returned from `main()`.
+ *
  * Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in
  * @flags, and on POSIX platforms, the same restrictions as for
  * g_child_watch_source_new() apply.
  *
  * If an error occurs, no data is returned in @standard_output,
- * @standard_error, or @exit_status.
+ * @standard_error, or @wait_status.
  *
  * This function calls g_spawn_async_with_pipes() internally; see that
  * function for full details on the other parameters and details on
@@ -31385,6 +31641,27 @@
 
 
 /**
+ * g_steal_fd:
+ * @fd_ptr: (not optional) (inout): A pointer to a file descriptor
+ *
+ * Sets @fd_ptr to `-1`, returning the value that was there before.
+ *
+ * Conceptually, this transfers the ownership of the file descriptor
+ * from the referenced variable to the caller of the function (i.e.
+ * ‘steals’ the reference). This is very similar to g_steal_pointer(),
+ * but for file descriptors.
+ *
+ * On POSIX platforms, this function is async-signal safe
+ * (see [`signal(7)`](man:signal(7)) and
+ * [`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a
+ * signal handler or a #GSpawnChildSetupFunc.
+ *
+ * Returns: the value that @fd_ptr previously had
+ * Since: 2.70
+ */
+
+
+/**
  * g_stpcpy:
  * @dest: destination buffer.
  * @src: source string.
@@ -31574,21 +31851,24 @@
  * @substitutor: replacement character for disallowed bytes
  *
  * For each character in @string, if the character is not in @valid_chars,
- * replaces the character with @substitutor. Modifies @string in place,
- * and return @string itself, not a copy. The return value is to allow
- * nesting such as
+ * replaces the character with @substitutor.
+ *
+ * Modifies @string in place, and return @string itself, not a copy. The
+ * return value is to allow nesting such as:
+ *
  * |[<!-- language="C" -->
  *   g_ascii_strup (g_strcanon (str, "abc", '?'))
  * ]|
  *
- * In order to modify a copy, you may use `g_strdup()`:
+ * In order to modify a copy, you may use g_strdup():
+ *
  * |[<!-- language="C" -->
  *   reformatted = g_strcanon (g_strdup (const_str), "abc", '?');
  *   ...
  *   g_free (reformatted);
  * ]|
  *
- * Returns: @string
+ * Returns: the modified @string
  */
 
 
@@ -31698,22 +31978,26 @@
  * @new_delimiter: the new delimiter character
  *
  * Converts any delimiter characters in @string to @new_delimiter.
+ *
  * Any characters in @string which are found in @delimiters are
  * changed to the @new_delimiter character. Modifies @string in place,
- * and returns @string itself, not a copy. The return value is to
- * allow nesting such as
+ * and returns @string itself, not a copy.
+ *
+ * The return value is to allow nesting such as:
+ *
  * |[<!-- language="C" -->
  *   g_ascii_strup (g_strdelimit (str, "abc", '?'))
  * ]|
  *
- * In order to modify a copy, you may use `g_strdup()`:
+ * In order to modify a copy, you may use g_strdup():
+ *
  * |[<!-- language="C" -->
  *   reformatted = g_strdelimit (g_strdup (const_str), "abc", '?');
  *   ...
  *   g_free (reformatted);
  * ]|
  *
- * Returns: @string
+ * Returns: the modified @string
  */
 
 
@@ -32377,8 +32661,13 @@
  *
  * Replaces the string @find with the string @replace in a #GString up to
  * @limit times. If the number of instances of @find in the #GString is
- * less than @limit, all instances are replaced. If the number of
- * instances is `0`, all instances of @find are replaced.
+ * less than @limit, all instances are replaced. If @limit is `0`,
+ * all instances of @find are replaced.
+ *
+ * If @find is the empty string, since versions 2.69.1 and 2.68.4 the
+ * replacement will be inserted no more than once per possible position
+ * (beginning of string, end of string and between characters). This did
+ * not work correctly in earlier versions.
  *
  * Returns: the number of find and replace operations performed.
  * Since: 2.68
@@ -32841,6 +33130,28 @@
 
 
 /**
+ * g_strv_builder_add_many:
+ * @builder: a #GStrvBuilder
+ * @...: one or more strings followed by %NULL
+ *
+ * Appends all the given strings to the builder.
+ *
+ * Since 2.70
+ */
+
+
+/**
+ * g_strv_builder_addv:
+ * @builder: a #GStrvBuilder
+ * @value: (array zero-terminated=1): the vector of strings to add
+ *
+ * Appends all the strings in the given vector to the builder.
+ *
+ * Since 2.70
+ */
+
+
+/**
  * g_strv_builder_end:
  * @builder: a #GStrvBuilder
  *
@@ -33010,15 +33321,19 @@
 
 /**
  * g_test_bug:
- * @bug_uri_snippet: Bug specific bug tracker URI portion.
+ * @bug_uri_snippet: Bug specific bug tracker URI or URI portion.
  *
  * This function adds a message to test reports that
  * associates a bug URI with a test case.
+ *
  * Bug URIs are constructed from a base URI set with g_test_bug_base()
  * and @bug_uri_snippet. If g_test_bug_base() has not been called, it is
  * assumed to be the empty string, so a full URI can be provided to
  * g_test_bug() instead.
  *
+ * Since GLib 2.70, the base URI is not prepended to @bug_uri_snippet if it
+ * is already a valid URI.
+ *
  * Since: 2.16:
  * See also: g_test_summary()
  */
@@ -33038,7 +33353,7 @@
  * case only.
  * Bug URIs are constructed by appending a bug specific URI
  * portion to @uri_pattern, or by replacing the special string
- * '\%s' within @uri_pattern if that is present.
+ * `%s` within @uri_pattern if that is present.
  *
  * If g_test_bug_base() is not called, bug URIs are formed solely
  * from the value provided by g_test_bug().
@@ -33082,6 +33397,16 @@
 
 
 /**
+ * g_test_case_free:
+ * @test_case: a #GTestCase
+ *
+ * Free the @test_case.
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * g_test_create_case:
  * @test_name: the name for the test case
  * @data_size: the size of the fixture data structure
@@ -33761,6 +34086,16 @@
 
 
 /**
+ * g_test_suite_free:
+ * @suite: a #GTestSuite
+ *
+ * Free the @suite and all nested #GTestSuites.
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * g_test_summary:
  * @summary: One or two sentences summarising what the test checks, and how it
  *    checks it.
@@ -34296,6 +34631,28 @@
 
 
 /**
+ * g_thread_pool_new_full:
+ * @func: a function to execute in the threads of the new thread pool
+ * @user_data: user data that is handed over to @func every time it
+ *     is called
+ * @item_free_func: (nullable): used to pass as a free function to
+ *     g_async_queue_new_full()
+ * @max_threads: the maximal number of threads to execute concurrently
+ *     in the new thread pool, `-1` means no limit
+ * @exclusive: should this thread pool be exclusive?
+ * @error: return location for error, or %NULL
+ *
+ * This function creates a new thread pool similar to g_thread_pool_new()
+ * but allowing @item_free_func to be specified to free the data passed
+ * to g_thread_pool_push() in the case that the #GThreadPool is stopped
+ * and freed before all tasks have been executed.
+ *
+ * Returns: (transfer full): the new #GThreadPool
+ * Since: 2.70
+ */
+
+
+/**
  * g_thread_pool_push:
  * @pool: a #GThreadPool
  * @data: a new task for @pool
@@ -34892,15 +35249,17 @@
 /**
  * g_timeout_add:
  * @interval: the time between calls to the function, in milliseconds
- *             (1/1000ths of a second)
+ *    (1/1000ths of a second)
  * @function: function to call
  * @data: data to pass to @function
  *
  * Sets a function to be called at regular intervals, with the default
- * priority, #G_PRIORITY_DEFAULT.  The function is called repeatedly
- * until it returns %FALSE, at which point the timeout is automatically
- * destroyed and the function will not be called again.  The first call
- * to the function will be at the end of the first @interval.
+ * priority, %G_PRIORITY_DEFAULT.
+ *
+ * The given @function is called repeatedly until it returns %G_SOURCE_REMOVE
+ * or %FALSE, at which point the timeout is automatically destroyed and the
+ * function will not be called again. The first call to the function will be
+ * at the end of the first @interval.
  *
  * Note that timeout functions may be delayed, due to the processing of other
  * event sources. Thus they should not be relied on for precise timing.
@@ -34934,9 +35293,9 @@
 /**
  * g_timeout_add_full: (rename-to g_timeout_add)
  * @priority: the priority of the timeout source. Typically this will be in
- *            the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
+ *   the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH.
  * @interval: the time between calls to the function, in milliseconds
- *             (1/1000ths of a second)
+ *   (1/1000ths of a second)
  * @function: function to call
  * @data: data to pass to @function
  * @notify: (nullable): function to call when the timeout is removed, or %NULL
@@ -34977,8 +35336,10 @@
  * @data: data to pass to @function
  *
  * Sets a function to be called at regular intervals with the default
- * priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until
- * it returns %FALSE, at which point the timeout is automatically destroyed
+ * priority, %G_PRIORITY_DEFAULT.
+ *
+ * The function is called repeatedly until it returns %G_SOURCE_REMOVE
+ * or %FALSE, at which point the timeout is automatically destroyed
  * and the function will not be called again.
  *
  * This internally creates a main loop source using
@@ -35006,24 +35367,25 @@
 /**
  * g_timeout_add_seconds_full: (rename-to g_timeout_add_seconds)
  * @priority: the priority of the timeout source. Typically this will be in
- *            the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
+ *   the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH.
  * @interval: the time between calls to the function, in seconds
  * @function: function to call
  * @data: data to pass to @function
  * @notify: (nullable): function to call when the timeout is removed, or %NULL
  *
  * Sets a function to be called at regular intervals, with @priority.
- * The function is called repeatedly until it returns %FALSE, at which
- * point the timeout is automatically destroyed and the function will
- * not be called again.
+ *
+ * The function is called repeatedly until it returns %G_SOURCE_REMOVE
+ * or %FALSE, at which point the timeout is automatically destroyed and
+ * the function will not be called again.
  *
  * Unlike g_timeout_add(), this function operates at whole second granularity.
  * The initial starting point of the timer is determined by the implementation
  * and the implementation is expected to group multiple timers together so that
- * they fire all at the same time.
- * To allow this grouping, the @interval to the first timer is rounded
- * and can deviate up to one second from the specified interval.
- * Subsequent timer iterations will generally run at the specified interval.
+ * they fire all at the same time. To allow this grouping, the @interval to the
+ * first timer is rounded and can deviate up to one second from the specified
+ * interval. Subsequent timer iterations will generally run at the specified
+ * interval.
  *
  * Note that timeout functions may be delayed, due to the processing of other
  * event sources. Thus they should not be relied on for precise timing.
@@ -35559,6 +35921,17 @@
 
 
 /**
+ * g_tree_remove_all:
+ * @tree: a #GTree
+ *
+ * Removes all nodes from a #GTree and destroys their keys and values,
+ * then resets the #GTree’s root to %NULL.
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * g_tree_replace:
  * @tree: a #GTree
  * @key: the key to insert
@@ -35783,10 +36156,10 @@
  * @str: a UCS-4 encoded string
  * @len: the maximum length (number of characters) of @str to use.
  *     If @len < 0, then the string is nul-terminated.
- * @items_read: (out caller-allocates) (optional): location to store number of
+ * @items_read: (out) (optional): location to store number of
  *     bytes read, or %NULL. If an error occurs then the index of the invalid
  *     input is stored here.
- * @items_written: (out caller-allocates) (optional): location to store number
+ * @items_written: (out) (optional): location to store number
  *     of #gunichar2  written, or %NULL. The value stored here does not include
  *     the trailing 0.
  * @error: location to store the error occurring, or %NULL to ignore
@@ -35807,9 +36180,9 @@
  * @str: a UCS-4 encoded string
  * @len: the maximum length (number of characters) of @str to use.
  *     If @len < 0, then the string is nul-terminated.
- * @items_read: (out caller-allocates) (optional): location to store number of
+ * @items_read: (out) (optional): location to store number of
  *     characters read, or %NULL.
- * @items_written: (out caller-allocates) (optional): location to store number
+ * @items_written: (out) (optional): location to store number
  *     of bytes written or %NULL. The value here stored does not include the
  *     trailing 0 byte.
  * @error: location to store the error occurring, or %NULL to ignore
@@ -37498,11 +37871,11 @@
  * @str: a UTF-16 encoded string
  * @len: the maximum length (number of #gunichar2) of @str to use.
  *     If @len < 0, then the string is nul-terminated.
- * @items_read: (out caller-allocates) (optional): location to store number of
+ * @items_read: (out) (optional): location to store number of
  *     words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will
  *     be returned in case @str contains a trailing partial character. If
  *     an error occurs then the index of the invalid input is stored here.
- * @items_written: (out caller-allocates) (optional): location to store number
+ * @items_written: (out) (optional): location to store number
  *     of characters written, or %NULL. The value stored here does not include
  *     the trailing 0 character.
  * @error: location to store the error occurring, or %NULL to ignore
@@ -37523,11 +37896,11 @@
  * @str: a UTF-16 encoded string
  * @len: the maximum length (number of #gunichar2) of @str to use.
  *     If @len < 0, then the string is nul-terminated.
- * @items_read: (out caller-allocates) (optional): location to store number of
+ * @items_read: (out) (optional): location to store number of
  *     words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will
  *     be returned in case @str contains a trailing partial character. If
  *     an error occurs then the index of the invalid input is stored here.
- * @items_written: (out caller-allocates) (optional): location to store number
+ * @items_written: (out) (optional): location to store number
  *     of bytes written, or %NULL. The value stored here does not include the
  *     trailing 0 byte.
  * @error: location to store the error occurring, or %NULL to ignore
@@ -37967,13 +38340,13 @@
  * @str: a UTF-8 encoded string
  * @len: the maximum length of @str to use, in bytes. If @len < 0,
  *     then the string is nul-terminated.
- * @items_read: (out caller-allocates) (optional): location to store number of
+ * @items_read: (out) (optional): location to store number of
  *    bytes read, or %NULL.
  *     If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be
  *     returned in case @str contains a trailing partial
  *     character. If an error occurs then the index of the
  *     invalid input is stored here.
- * @items_written: (out caller-allocates) (optional): location to store number
+ * @items_written: (out) (optional): location to store number
  *     of characters written or %NULL. The value here stored does not include
  *     the trailing 0 character.
  * @error: location to store the error occurring, or %NULL to ignore
@@ -37995,7 +38368,7 @@
  * @str: a UTF-8 encoded string
  * @len: the maximum length of @str to use, in bytes. If @len < 0,
  *     then the string is nul-terminated.
- * @items_written: (out caller-allocates) (optional): location to store the
+ * @items_written: (out) (optional): location to store the
  *     number of characters in the result, or %NULL.
  *
  * Convert a string from UTF-8 to a 32-bit fixed width
@@ -38014,11 +38387,11 @@
  * @str: a UTF-8 encoded string
  * @len: the maximum length (number of bytes) of @str to use.
  *     If @len < 0, then the string is nul-terminated.
- * @items_read: (out caller-allocates) (optional): location to store number of
+ * @items_read: (out) (optional): location to store number of
  *     bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will
  *     be returned in case @str contains a trailing partial character. If
  *     an error occurs then the index of the invalid input is stored here.
- * @items_written: (out caller-allocates) (optional): location to store number
+ * @items_written: (out) (optional): location to store number
  *     of #gunichar2 written, or %NULL. The value stored here does not include
  *     the trailing 0.
  * @error: location to store the error occurring, or %NULL to ignore
@@ -38983,7 +39356,7 @@
  *
  * Note that values borrowed from the returned child are not guaranteed to
  * still be valid after the child is freed even if you still hold a reference
- * to @value, if @value has not been serialised at the time this function is
+ * to @value, if @value has not been serialized at the time this function is
  * called. To avoid this, you can serialize @value by calling
  * g_variant_get_data() and optionally ignoring the return value.
  *
@@ -39003,33 +39376,33 @@
  * g_variant_get_data:
  * @value: a #GVariant instance
  *
- * Returns a pointer to the serialised form of a #GVariant instance.
+ * Returns a pointer to the serialized form of a #GVariant instance.
  * The returned data may not be in fully-normalised form if read from an
  * untrusted source.  The returned data must not be freed; it remains
  * valid for as long as @value exists.
  *
- * If @value is a fixed-sized value that was deserialised from a
- * corrupted serialised container then %NULL may be returned.  In this
+ * If @value is a fixed-sized value that was deserialized from a
+ * corrupted serialized container then %NULL may be returned.  In this
  * case, the proper thing to do is typically to use the appropriate
  * number of nul bytes in place of @value.  If @value is not fixed-sized
  * then %NULL is never returned.
  *
- * In the case that @value is already in serialised form, this function
- * is O(1).  If the value is not already in serialised form,
- * serialisation occurs implicitly and is approximately O(n) in the size
+ * In the case that @value is already in serialized form, this function
+ * is O(1).  If the value is not already in serialized form,
+ * serialization occurs implicitly and is approximately O(n) in the size
  * of the result.
  *
- * To deserialise the data returned by this function, in addition to the
- * serialised data, you must know the type of the #GVariant, and (if the
+ * To deserialize the data returned by this function, in addition to the
+ * serialized data, you must know the type of the #GVariant, and (if the
  * machine might be different) the endianness of the machine that stored
  * it. As a result, file formats or network messages that incorporate
- * serialised #GVariants must include this information either
+ * serialized #GVariants must include this information either
  * implicitly (for instance "the file always contains a
  * %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or
  * explicitly (by storing the type and/or endianness in addition to the
- * serialised data).
+ * serialized data).
  *
- * Returns: (transfer none): the serialised form of @value, or %NULL
+ * Returns: (transfer none): the serialized form of @value, or %NULL
  * Since: 2.24
  */
 
@@ -39038,7 +39411,7 @@
  * g_variant_get_data_as_bytes:
  * @value: a #GVariant
  *
- * Returns a pointer to the serialised form of a #GVariant instance.
+ * Returns a pointer to the serialized form of a #GVariant instance.
  * The semantics of this function are exactly the same as
  * g_variant_get_data(), except that the returned #GBytes holds
  * a reference to the variant data.
@@ -39068,7 +39441,7 @@
  * @n_elements: (out): a pointer to the location to store the number of items
  * @element_size: the size of each element
  *
- * Provides access to the serialised data for an array of fixed-sized
+ * Provides access to the serialized data for an array of fixed-sized
  * items.
  *
  * @value must be an array with fixed-sized elements.  Numeric types are
@@ -39076,7 +39449,7 @@
  *
  * @element_size must be the size of a single element in the array,
  * as given by the section on
- * [serialized data memory][gvariant-serialised-data-memory].
+ * [serialized data memory][gvariant-serialized-data-memory].
  *
  * In particular, arrays of these fixed-sized types can be interpreted
  * as an array of the given C type, with @element_size set to the size
@@ -39089,7 +39462,7 @@
  *
  * For example, if calling this function for an array of 32-bit integers,
  * you might say `sizeof(gint32)`. This value isn't used except for the purpose
- * of a double-check that the form of the serialised data matches the caller's
+ * of a double-check that the form of the serialized data matches the caller's
  * expectation.
  *
  * @n_elements, which must be non-%NULL, is set equal to the number of
@@ -39191,7 +39564,7 @@
  * #GVariant is created with the same value as @value.
  *
  * It makes sense to call this function if you've received #GVariant
- * data from untrusted sources and you want to ensure your serialised
+ * data from untrusted sources and you want to ensure your serialized
  * output is definitely in normal form.
  *
  * If @value is already in normal form, a new reference will be returned
@@ -39237,13 +39610,13 @@
  * If @value has a fixed-sized type then this function always returned
  * that fixed size.
  *
- * In the case that @value is already in serialised form or the size has
+ * In the case that @value is already in serialized form or the size has
  * already been calculated (ie: this function has been called before)
  * then this function is O(1).  Otherwise, the size is calculated, an
  * operation which is approximately O(n) in the number of values
  * involved.
  *
- * Returns: the serialised size of @value
+ * Returns: the serialized size of @value
  * Since: 2.24
  */
 
@@ -39473,7 +39846,7 @@
  * Checks if @value is in normal form.
  *
  * The main reason to do this is to detect if a given chunk of
- * serialised data is in normal form: load the data into a #GVariant
+ * serialized data is in normal form: load the data into a #GVariant
  * using g_variant_new_from_data() and then use this function to
  * check.
  *
@@ -40027,7 +40400,7 @@
  * @element_size must be the size of a single element in the array.
  * For example, if calling this function for an array of 32-bit integers,
  * you might say sizeof(gint32). This value isn't used except for the purpose
- * of a double-check that the form of the serialised data matches the caller's
+ * of a double-check that the form of the serialized data matches the caller's
  * expectation.
  *
  * @n_elements must be the length of the @elements array.
@@ -40043,8 +40416,8 @@
  * @bytes: a #GBytes
  * @trusted: if the contents of @bytes are trusted
  *
- * Constructs a new serialised-mode #GVariant instance.  This is the
- * inner interface for creation of new serialised values that gets
+ * Constructs a new serialized-mode #GVariant instance.  This is the
+ * inner interface for creation of new serialized values that gets
  * called from various functions in gvariant.c.
  *
  * A reference is taken on @bytes.
@@ -40061,13 +40434,13 @@
 /**
  * g_variant_new_from_data:
  * @type: a definite #GVariantType
- * @data: (array length=size) (element-type guint8): the serialised data
+ * @data: (array length=size) (element-type guint8): the serialized data
  * @size: the size of @data
  * @trusted: %TRUE if @data is definitely in normal form
  * @notify: (scope async): function to call when @data is no longer needed
  * @user_data: data for @notify
  *
- * Creates a new #GVariant instance from serialised data.
+ * Creates a new #GVariant instance from serialized data.
  *
  * @type is the type of #GVariant instance that will be constructed.
  * The interpretation of @data depends on knowing the type.
@@ -40077,8 +40450,8 @@
  * @user_data.  If the contents of @data change before that time then
  * the result is undefined.
  *
- * If @data is trusted to be serialised data in normal form then
- * @trusted should be %TRUE.  This applies to serialised data created
+ * If @data is trusted to be serialized data in normal form then
+ * @trusted should be %TRUE.  This applies to serialized data created
  * within this process or read from a trusted location on the disk (such
  * as a file installed in /usr/lib alongside your application).  You
  * should set trusted to %FALSE if @data is read from the network, a
@@ -40651,17 +41024,17 @@
 /**
  * g_variant_store:
  * @value: the #GVariant to store
- * @data: (not nullable): the location to store the serialised data at
+ * @data: (not nullable): the location to store the serialized data at
  *
- * Stores the serialised form of @value at @data.  @data should be
+ * Stores the serialized form of @value at @data.  @data should be
  * large enough.  See g_variant_get_size().
  *
  * The stored data is in machine native byte order but may not be in
  * fully-normalised form if read from an untrusted source.  See
  * g_variant_get_normal_form() for a solution.
  *
- * As with g_variant_get_data(), to be able to deserialise the
- * serialised variant successfully, its type and (if the destination
+ * As with g_variant_get_data(), to be able to deserialize the
+ * serialized variant successfully, its type and (if the destination
  * machine might be different) its endianness must also be available.
  *
  * This function is approximately O(n) in the size of @data.
@@ -41918,24 +42291,25 @@
  * @required_micro: the required micro version
  *
  * Checks that the GLib library in use is compatible with the
- * given version. Generally you would pass in the constants
- * #GLIB_MAJOR_VERSION, #GLIB_MINOR_VERSION, #GLIB_MICRO_VERSION
- * as the three arguments to this function; that produces
- * a check that the library in use is compatible with
- * the version of GLib the application or module was compiled
- * against.
+ * given version.
+ *
+ * Generally you would pass in the constants %GLIB_MAJOR_VERSION,
+ * %GLIB_MINOR_VERSION, %GLIB_MICRO_VERSION as the three arguments
+ * to this function; that produces a check that the library in use
+ * is compatible with the version of GLib the application or module
+ * was compiled against.
  *
  * Compatibility is defined by two things: first the version
  * of the running library is newer than the version
- * @required_major.required_minor.@required_micro. Second
+ * `@required_major.required_minor.@required_micro`. Second
  * the running library must be binary compatible with the
- * version @required_major.required_minor.@required_micro
+ * version `@required_major.@required_minor.@required_micro`
  * (same major version.)
  *
- * Returns: %NULL if the GLib library is compatible with the
- *     given version, or a string describing the version mismatch.
- *     The returned string is owned by GLib and must not be modified
- *     or freed.
+ * Returns: (transfer none) (nullable): %NULL if the GLib library is
+ *   compatible with the given version, or a string describing the
+ *   version mismatch. The returned string is owned by GLib and must
+ *   not be modified or freed.
  * Since: 2.6
  */
 
diff --git a/gir/gmodule-2.0.c b/gir/gmodule-2.0.c
index dbacb484..988a8b0f 100644
--- a/gir/gmodule-2.0.c
+++ b/gir/gmodule-2.0.c
@@ -37,6 +37,15 @@
 
 
 /**
+ * G_MODULE_ERROR:
+ *
+ * The error domain of the #GModule API.
+ *
+ * Since: 2.70
+ */
+
+
+/**
  * G_MODULE_EXPORT:
  *
  * Used to declare functions exported by libraries or modules.
@@ -218,22 +227,37 @@
  * @file_name: (nullable): the name of the file containing the module, or %NULL
  *     to obtain a #GModule representing the main program itself
  * @flags: the flags used for opening the module. This can be the
+ *     logical OR of any of the #GModuleFlags.
+ *
+ * A thin wrapper function around g_module_open_full()
+ *
+ * Returns: a #GModule on success, or %NULL on failure
+ */
+
+
+/**
+ * g_module_open_full:
+ * @file_name: (nullable): the name of the file containing the module, or %NULL
+ *     to obtain a #GModule representing the main program itself
+ * @flags: the flags used for opening the module. This can be the
  *     logical OR of any of the #GModuleFlags
+ * @error: #GError.
  *
  * Opens a module. If the module has already been opened,
  * its reference count is incremented.
  *
- * First of all g_module_open() tries to open @file_name as a module.
+ * First of all g_module_open_full() tries to open @file_name as a module.
  * If that fails and @file_name has the ".la"-suffix (and is a libtool
  * archive) it tries to open the corresponding module. If that fails
  * and it doesn't have the proper module suffix for the platform
  * (#G_MODULE_SUFFIX), this suffix will be appended and the corresponding
  * module will be opened. If that fails and @file_name doesn't have the
- * ".la"-suffix, this suffix is appended and g_module_open() tries to open
+ * ".la"-suffix, this suffix is appended and g_module_open_full() tries to open
  * the corresponding module. If eventually that fails as well, %NULL is
  * returned.
  *
  * Returns: a #GModule on success, or %NULL on failure
+ * Since: 2.70
  */
 
 
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index eaecc72d..93a4c7d3 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -75,11 +75,13 @@
  * This signal is typically used to obtain change notification for a
  * single property, by specifying the property name as a detail in the
  * g_signal_connect() call, like this:
+ *
  * |[<!-- language="C" -->
  * g_signal_connect (text_view->buffer, "notify::paste-target-list",
  *                   G_CALLBACK (gtk_text_view_target_list_notify),
  *                   text_view)
  * ]|
+ *
  * It is important to note that you must use
  * [canonical parameter names][canonical-parameter-names] as
  * detail strings for the notify signal.
@@ -90,20 +92,22 @@
  * GParamSpecPool:
  *
  * A #GParamSpecPool maintains a collection of #GParamSpecs which can be
- * quickly accessed by owner and name. The implementation of the #GObject property
- * system uses such a pool to store the #GParamSpecs of the properties all object
- * types.
+ * quickly accessed by owner and name.
+ *
+ * The implementation of the #GObject property system uses such a pool to
+ * store the #GParamSpecs of the properties all object types.
  */
 
 
 /**
  * GWeakRef:
  *
- * A structure containing a weak reference to a #GObject.  It can either
- * be empty (i.e. point to %NULL), or point to an object for as long as
- * at least one "strong" reference to that object exists. Before the
- * object's #GObjectClass.dispose method is called, every #GWeakRef
- * associated with becomes empty (i.e. points to %NULL).
+ * A structure containing a weak reference to a #GObject.
+ *
+ * A `GWeakRef` can either be empty (i.e. point to %NULL), or point to an
+ * object for as long as at least one "strong" reference to that object
+ * exists. Before the object's #GObjectClass.dispose method is called,
+ * every #GWeakRef associated with becomes empty (i.e. points to %NULL).
  *
  * Like #GValue, #GWeakRef can be statically allocated, stack- or
  * heap-allocated, or embedded in larger structures.
@@ -166,9 +170,10 @@
  *
  * #GBinding is the representation of a binding between a property on a
  * #GObject instance (or source) and another property on another #GObject
- * instance (or target). Whenever the source property changes, the same
- * value is applied to the target property; for instance, the following
- * binding:
+ * instance (or target).
+ *
+ * Whenever the source property changes, the same value is applied to the
+ * target property; for instance, the following binding:
  *
  * |[<!-- language="C" -->
  *   g_object_bind_property (object1, "property-a",
@@ -251,10 +256,11 @@
  * @see_also: #GParamSpecBoxed, g_param_spec_boxed()
  * @title: Boxed Types
  *
- * #GBoxed is a generic wrapper mechanism for arbitrary C structures. The only
- * thing the type system needs to know about the structures is how to copy them
- * (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc) — beyond that
- * they are treated as opaque chunks of memory.
+ * #GBoxed is a generic wrapper mechanism for arbitrary C structures.
+ *
+ * The only thing the type system needs to know about the structures is how to
+ * copy them (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc);
+ * beyond that, they are treated as opaque chunks of memory.
  *
  * Boxed types are useful for simple value-holder structures like rectangles or
  * points. They can also be used for wrapping structures defined in non-#GObject
@@ -277,8 +283,9 @@
  * @short_description: Functions as first-class objects
  * @title: Closures
  *
- * A #GClosure represents a callback supplied by the programmer. It
- * will generally comprise a function of some kind and a marshaller
+ * A #GClosure represents a callback supplied by the programmer.
+ *
+ * It will generally comprise a function of some kind and a marshaller
  * used to call it. It is the responsibility of the marshaller to
  * convert the arguments for the invocation from #GValues into
  * a suitable form, perform the callback on the converted arguments,
@@ -336,11 +343,16 @@
  *
  * The #GValue structure is basically a variable container that consists
  * of a type identifier and a specific value of that type.
+ *
  * The type identifier within a #GValue structure always determines the
  * type of the associated value.
+ *
  * To create an undefined #GValue structure, simply create a zero-filled
  * #GValue structure. To initialize the #GValue, use the g_value_init()
- * function. A #GValue cannot be used until it is initialized.
+ * function. A #GValue cannot be used until it is initialized. Before
+ * destruction you must always use g_value_unset() to make sure allocated
+ * memory is freed.
+ *
  * The basic type operations (such as freeing and copying) are determined
  * by the #GTypeValueTable associated with the type ID stored in the #GValue.
  * Other #GValue operations (such as converting values between types) are
@@ -403,6 +415,34 @@
  *   return 0;
  * }
  * ]|
+ *
+ * See also [gobject-Standard-Parameter-and-Value-Types] for more information on
+ * validation of #GValue.
+ *
+ * For letting a #GValue own (and memory manage) arbitrary types or pointers,
+ * they need to become a [boxed type][gboxed]. The example below shows how
+ * the pointer `mystruct` of type `MyStruct` is used as a [boxed type][gboxed].
+ *
+ * |[<!-- language="C" -->
+ * typedef struct { ... } MyStruct;
+ * G_DEFINE_BOXED_TYPE (MyStruct, my_struct, my_struct_copy, my_struct_free)
+ *
+ * // These two lines normally go in a public header. By GObject convention,
+ * // the naming scheme is NAMESPACE_TYPE_NAME:
+ * #define MY_TYPE_STRUCT (my_struct_get_type ())
+ * GType my_struct_get_type (void);
+ *
+ * void
+ * foo ()
+ * {
+ *   GValue *value = g_new0 (GValue, 1);
+ *   g_value_init (value, MY_TYPE_STRUCT);
+ *   g_value_set_boxed (value, mystruct);
+ *   // [... your code ....]
+ *   g_value_unset (value);
+ *   g_value_free (value);
+ * }
+ * ]|
  */
 
 
@@ -436,7 +476,7 @@
  *     management system
  * @title: Type Information
  *
- * The GType API is the foundation of the GObject system.  It provides the
+ * The GType API is the foundation of the GObject system. It provides the
  * facilities for registering and managing all fundamental data types,
  * user-defined object and interface types.
  *
@@ -483,16 +523,20 @@
  * @title: GTypeModule
  *
  * #GTypeModule provides a simple implementation of the #GTypePlugin
- * interface. The model of #GTypeModule is a dynamically loaded module
- * which implements some number of types and interface implementations.
+ * interface.
+ *
+ * The model of #GTypeModule is a dynamically loaded module which
+ * implements some number of types and interface implementations.
+ *
  * When the module is loaded, it registers its types and interfaces
  * using g_type_module_register_type() and g_type_module_add_interface().
  * As long as any instances of these types and interface implementations
  * are in use, the module is kept loaded. When the types and interfaces
  * are gone, the module may be unloaded. If the types and interfaces
  * become used again, the module will be reloaded. Note that the last
- * unref cannot happen in module code, since that would lead to the
- * caller's code being unloaded before g_object_unref() returns to it.
+ * reference cannot be released from within the module code, since that
+ * would lead to the caller's code being unloaded before g_object_unref()
+ * returns to it.
  *
  * Keeping track of whether the module should be loaded or not is done by
  * using a use count - it starts at zero, and whenever it is greater than
@@ -517,9 +561,10 @@
  * @see_also: #GTypeModule and g_type_register_dynamic().
  * @title: GTypePlugin
  *
+ * An interface that handles the lifecycle of dynamically loaded types.
+ *
  * The GObject type system supports dynamic loading of types.
- * The #GTypePlugin interface is used to handle the lifecycle
- * of dynamically loaded types. It goes as follows:
+ * It goes as follows:
  *
  * 1. The type is initially introduced (usually upon loading the module
  *    the first time, or by your main application that knows what modules
@@ -600,15 +645,18 @@
  * claimed to be "owned" by any code portion. The main motivation for
  * providing floating references is C convenience. In particular, it
  * allows code to be written as:
+ *
  * |[<!-- language="C" -->
  * container = create_container ();
  * container_add_child (container, create_child());
  * ]|
+ *
  * If container_add_child() calls g_object_ref_sink() on the passed-in child,
  * no reference of the newly created child is leaked. Without floating
  * references, container_add_child() can only g_object_ref() the new child,
  * so to implement this code without reference leaks, it would have to be
  * written as:
+ *
  * |[<!-- language="C" -->
  * Child *child;
  * container = create_container ();
@@ -616,6 +664,7 @@
  * container_add_child (container, child);
  * g_object_unref (child);
  * ]|
+ *
  * The floating reference can be converted into an ordinary reference by
  * calling g_object_ref_sink(). For already sunken objects (objects that
  * don't have a floating reference anymore), g_object_ref_sink() is equivalent
@@ -680,6 +729,8 @@
  * Parameter names need to start with a letter (a-z or A-Z). Subsequent
  * characters can be letters, numbers or a '-'.
  * All other characters are replaced by a '-' during construction.
+ *
+ * See also #GValue for more information.
  */
 
 
@@ -969,8 +1020,14 @@
  * @boxed_free: Boxed structure free function.
  *
  * This function creates a new %G_TYPE_BOXED derived type id for a new
- * boxed type with name @name. Boxed type handling functions have to be
- * provided to copy and free opaque boxed structures of this type.
+ * boxed type with name @name.
+ *
+ * Boxed type handling functions have to be provided to copy and free
+ * opaque boxed structures of this type.
+ *
+ * For the general case, it is recommended to use #G_DEFINE_BOXED_TYPE
+ * instead of calling g_boxed_type_register_static() directly. The macro
+ * will create the appropriate `*_get_type()` function for the boxed type.
  *
  * Returns: New %G_TYPE_BOXED derived type id for @name.
  */
@@ -1909,11 +1966,12 @@
  * @notify_func: the callback function to register
  *
  * Registers a finalization notifier which will be called when the
- * reference count of @closure goes down to 0. Multiple finalization
- * notifiers on a single closure are invoked in unspecified order. If
- * a single call to g_closure_unref() results in the closure being
- * both invalidated and finalized, then the invalidate notifiers will
- * be run before the finalize notifiers.
+ * reference count of @closure goes down to 0.
+ *
+ * Multiple finalization notifiers on a single closure are invoked in
+ * unspecified order. If a single call to g_closure_unref() results in
+ * the closure being both invalidated and finalized, then the invalidate
+ * notifiers will be run before the finalize notifiers.
  */
 
 
@@ -1924,9 +1982,10 @@
  * @notify_func: the callback function to register
  *
  * Registers an invalidation notifier which will be called when the
- * @closure is invalidated with g_closure_invalidate(). Invalidation
- * notifiers are invoked before finalization notifiers, in an
- * unspecified order.
+ * @closure is invalidated with g_closure_invalidate().
+ *
+ * Invalidation notifiers are invoked before finalization notifiers,
+ * in an unspecified order.
  */
 
 
@@ -1941,9 +2000,11 @@
  * @post_marshal_notify: a function to call after the closure callback
  *
  * Adds a pair of notifiers which get invoked before and after the
- * closure callback, respectively. This is typically used to protect
- * the extra arguments for the duration of the callback. See
- * g_object_watch_closure() for an example of marshal guards.
+ * closure callback, respectively.
+ *
+ * This is typically used to protect the extra arguments for the
+ * duration of the callback. See g_object_watch_closure() for an
+ * example of marshal guards.
  */
 
 
@@ -1954,7 +2015,9 @@
  * Sets a flag on the closure to indicate that its calling
  * environment has become invalid, and thus causes any future
  * invocations of g_closure_invoke() on this @closure to be
- * ignored. Also, invalidation notifiers installed on the closure will
+ * ignored.
+ *
+ * Also, invalidation notifiers installed on the closure will
  * be called at this point. Note that unless you are holding a
  * reference to the closure yourself, the invalidation notifiers may
  * unref the closure and cause it to be destroyed, so if you need to
@@ -1970,7 +2033,7 @@
 /**
  * g_closure_invoke:
  * @closure: a #GClosure
- * @return_value: (optional) (out): a #GValue to store the return
+ * @return_value: (optional) (inout): 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
@@ -2006,8 +2069,9 @@
  * @data: data to store in the @data field of the newly allocated #GClosure
  *
  * Allocates a struct of the given size and initializes the initial
- * part as a #GClosure. This function is mainly useful when
- * implementing new types of closures.
+ * part as a #GClosure.
+ *
+ * This function is mainly useful when implementing new types of closures:
  *
  * |[<!-- language="C" -->
  * typedef struct _MyClosure MyClosure;
@@ -2088,12 +2152,16 @@
  * @closure: a #GClosure
  * @marshal: a #GClosureMarshal function
  *
- * Sets the marshaller of @closure. The `marshal_data`
- * of @marshal provides a way for a meta marshaller to provide additional
- * information to the marshaller. (See g_closure_set_meta_marshal().) For
- * GObject's C predefined marshallers (the g_cclosure_marshal_*()
+ * Sets the marshaller of @closure.
+ *
+ * The `marshal_data` of @marshal provides a way for a meta marshaller to
+ * provide additional information to the marshaller.
+ *
+ * For GObject's C predefined marshallers (the `g_cclosure_marshal_*()`
  * functions), what it provides is a callback function to use instead of
  * @closure->callback.
+ *
+ * See also: g_closure_set_meta_marshal()
  */
 
 
@@ -2104,12 +2172,15 @@
  *  to @meta_marshal
  * @meta_marshal: a #GClosureMarshal function
  *
- * Sets the meta marshaller of @closure.  A meta marshaller wraps
- * @closure->marshal and modifies the way it is called in some
- * fashion. The most common use of this facility is for C callbacks.
+ * Sets the meta marshaller of @closure.
+ *
+ * A meta marshaller wraps the @closure's marshal and modifies the way
+ * it is called in some fashion. The most common use of this facility
+ * is for C callbacks.
+ *
  * The same marshallers (generated by [glib-genmarshal][glib-genmarshal]),
  * are used everywhere, but the way that we get the callback function
- * differs. In most cases we want to use @closure->callback, but in
+ * differs. In most cases we want to use the @closure's callback, but in
  * other cases we want to use some different technique to retrieve the
  * callback function.
  *
@@ -2126,27 +2197,34 @@
  * @closure: #GClosure to decrement the initial reference count on, if it's
  *           still being held
  *
- * Takes over the initial ownership of a closure.  Each closure is
- * initially created in a "floating" state, which means that the initial
- * reference count is not owned by any caller. g_closure_sink() checks
- * to see if the object is still floating, and if so, unsets the
- * floating state and decreases the reference count. If the closure
- * is not floating, g_closure_sink() does nothing. The reason for the
- * existence of the floating state is to prevent cumbersome code
- * sequences like:
+ * Takes over the initial ownership of a closure.
+ *
+ * Each closure is initially created in a "floating" state, which means
+ * that the initial reference count is not owned by any caller.
+ *
+ * This function checks to see if the object is still floating, and if so,
+ * unsets the floating state and decreases the reference count. If the
+ * closure is not floating, g_closure_sink() does nothing.
+ *
+ * The reason for the existence of the floating state is to prevent
+ * cumbersome code sequences like:
+ *
  * |[<!-- language="C" -->
  * closure = g_cclosure_new (cb_func, cb_data);
  * g_source_set_closure (source, closure);
  * g_closure_unref (closure); // GObject doesn't really need this
  * ]|
+ *
  * Because g_source_set_closure() (and similar functions) take ownership of the
  * initial reference count, if it is unowned, we instead can write:
+ *
  * |[<!-- language="C" -->
  * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
  * ]|
  *
  * Generally, this function is used together with g_closure_ref(). An example
  * of storing a closure for later notification looks like:
+ *
  * |[<!-- language="C" -->
  * static GClosure *notify_closure = NULL;
  * void
@@ -2174,8 +2252,10 @@
  * @closure: #GClosure to decrement the reference count on
  *
  * Decrements the reference count of a closure after it was previously
- * incremented by the same caller. If no other callers are using the
- * closure, then the closure will be destroyed and freed.
+ * incremented by the same caller.
+ *
+ * If no other callers are using the closure, then the closure will be
+ * destroyed and freed.
  */
 
 
@@ -2432,10 +2512,12 @@
  * @flags: flags to pass to #GBinding
  *
  * Creates a binding between @source_property on @source and @target_property
- * on @target. Whenever the @source_property is changed the @target_property is
+ * on @target.
+ *
+ * Whenever the @source_property is changed the @target_property is
  * updated using the same value. For instance:
  *
- * |[
+ * |[<!-- language="C" -->
  *   g_object_bind_property (action, "active", widget, "sensitive", 0);
  * ]|
  *
@@ -3221,7 +3303,8 @@
  * @notify: a function to call when this reference is the
  *  last reference to the object, or is no longer
  *  the last reference.
- * @data: data to pass to @notify
+ * @data: (nullable): data to pass to @notify, or %NULL to
+ *  match any toggle refs with the @notify argument.
  *
  * Removes a reference added with g_object_add_toggle_ref(). The
  * reference count of the object is decreased by one.
@@ -3497,6 +3580,51 @@
 
 
 /**
+ * g_object_take_ref: (skip)
+ * @object: (type GObject.Object): a #GObject
+ *
+ * If @object is floating, sink it.  Otherwise, do nothing.
+ *
+ * In other words, this function will convert a floating reference (if
+ * present) into a full reference.
+ *
+ * Typically you want to use g_object_ref_sink() in order to
+ * automatically do the correct thing with respect to floating or
+ * non-floating references, but there is one specific scenario where
+ * this function is helpful.
+ *
+ * The situation where this function is helpful is when creating an API
+ * that allows the user to provide a callback function that returns a
+ * GObject. We certainly want to allow the user the flexibility to
+ * return a non-floating reference from this callback (for the case
+ * where the object that is being returned already exists).
+ *
+ * At the same time, the API style of some popular GObject-based
+ * libraries (such as Gtk) make it likely that for newly-created GObject
+ * instances, the user can be saved some typing if they are allowed to
+ * return a floating reference.
+ *
+ * Using this function on the return value of the user's callback allows
+ * the user to do whichever is more convenient for them. The caller will
+ * alway receives exactly one full reference to the value: either the
+ * one that was returned in the first place, or a floating reference
+ * that has been converted to a full reference.
+ *
+ * This function has an odd interaction when combined with
+ * g_object_ref_sink() running at the same time in another thread on
+ * the same #GObject instance. If g_object_ref_sink() runs first then
+ * the result will be that the floating reference is converted to a hard
+ * reference. If g_object_take_ref() runs first then the result will be
+ * that the floating reference is converted to a hard reference and an
+ * additional reference on top of that one is added. It is best to avoid
+ * this situation.
+ *
+ * Since: 2.70
+ * Returns: (type GObject.Object) (transfer full): @object
+ */
+
+
+/**
  * g_object_thaw_notify:
  * @object: a #GObject
  *
@@ -4282,10 +4410,12 @@
  * @name: 0-terminated string used as the name of the new #GParamSpec type.
  * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type.
  *
- * Registers @name as the name of a new static type derived from
- * #G_TYPE_PARAM. The type system uses the information contained in
- * the #GParamSpecTypeInfo structure pointed to by @info to manage the
- * #GParamSpec type and its instances.
+ * Registers @name as the name of a new static type derived
+ * from #G_TYPE_PARAM.
+ *
+ * The type system uses the information contained in the #GParamSpecTypeInfo
+ * structure pointed to by @info to manage the #GParamSpec type and its
+ * instances.
  *
  * Returns: The new type identifier.
  */
@@ -6910,6 +7040,7 @@
  * @v_boxed: (nullable): static boxed value to be set
  *
  * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
+ *
  * The boxed value is assumed to be static, and is thus not duplicated
  * when setting the #GValue.
  */
@@ -6934,7 +7065,7 @@
  * @value: a valid #GValue of type %G_TYPE_STRING
  * @v_string: (nullable): caller-owned string to be duplicated for the #GValue
  *
- * Set the contents of a %G_TYPE_STRING #GValue to @v_string.
+ * Set the contents of a %G_TYPE_STRING #GValue to a copy of @v_string.
  */