gir: Update annotations from GLib git master

3 files changed, 412 insertions, 148 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 615e4966..24bbb321 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -1654,7 +1654,7 @@
  *
  * The certificate database to use when verifying this TLS connection.
  * If no certificate database is set, then the default database will be
- * used. See g_dtls_backend_get_default_database().
+ * used. See g_tls_backend_get_default_database().
  *
  * Since: 2.48
  */
@@ -5454,13 +5454,16 @@
  * which are chained together by a #GAsyncReadyCallback. To begin
  * an asynchronous operation, provide a #GAsyncReadyCallback to the
  * asynchronous function. This callback will be triggered when the
- * operation has completed, and will be passed a #GAsyncResult instance
- * filled with the details of the operation's success or failure, the
- * object the asynchronous function was started for and any error codes
- * returned. The asynchronous callback function is then expected to call
- * the corresponding "_finish()" function, passing the object the
- * function was called for, the #GAsyncResult instance, and (optionally)
- * an @error to grab any error conditions that may have occurred.
+ * operation has completed, and must be run in a later iteration of
+ * the [thread-default main context][g-main-context-push-thread-default]
+ * from where the operation was initiated. It will be passed a
+ * #GAsyncResult instance filled with the details of the operation's
+ * success or failure, the object the asynchronous function was
+ * started for and any error codes returned. The asynchronous callback
+ * function is then expected to call the corresponding "_finish()"
+ * function, passing the object the function was called for, the
+ * #GAsyncResult instance, and (optionally) an @error to grab any
+ * error conditions that may have occurred.
  *
  * The "_finish()" function for an operation takes the generic result
  * (of type #GAsyncResult) and returns the specific result that the
@@ -6487,6 +6490,7 @@
  * - g_file_new_for_commandline_arg() for a command line argument.
  * - g_file_new_tmp() to create a temporary file from a template.
  * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name().
+ * - g_file_new_build_filename() to create a file from path elements.
  *
  * One way to think of a #GFile is as an abstraction of a pathname. For
  * normal files the system pathname is what is stored internally, but as
@@ -7393,9 +7397,9 @@
  * g_mount_unmount_with_operation() with (at least) the #GMount instance and a
  * #GAsyncReadyCallback.  The callback will be fired when the
  * operation has resolved (either with success or failure), and a
- * #GAsyncReady structure will be passed to the callback.  That
+ * #GAsyncResult structure will be passed to the callback.  That
  * callback should then call g_mount_unmount_with_operation_finish() with the #GMount
- * and the #GAsyncReady data to see if the operation was completed
+ * and the #GAsyncResult data to see if the operation was completed
  * successfully.  If an @error is present when g_mount_unmount_with_operation_finish()
  * is called, then it will be filled with any error information.
  */
@@ -8251,12 +8255,12 @@
  * implementations must carefully adhere to the expectations of
  * callers that are documented on each of the interface methods.
  *
- * Some of the GSettingsBackend functions accept or return a #GTree.
+ * Some of the #GSettingsBackend functions accept or return a #GTree.
  * These trees always have strings as keys and #GVariant as values.
  * g_settings_backend_create_tree() is a convenience function to create
  * suitable trees.
  *
- * The GSettingsBackend API is exported to allow third-party
+ * The #GSettingsBackend API is exported to allow third-party
  * implementations, but does not carry the same stability guarantees
  * as the public GIO API. For this reason, you have to define the
  * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including
@@ -8444,9 +8448,10 @@
  * from the point where it is called. g_simple_async_result_complete_in_idle()
  * will finish it from an idle handler in the
  * [thread-default main context][g-main-context-push-thread-default]
- * . g_simple_async_result_run_in_thread() will run the
- * job in a separate thread and then deliver the result to the
- * thread-default main context.
+ * where the #GSimpleAsyncResult was created.
+ * g_simple_async_result_run_in_thread() will run the job in a
+ * separate thread and then use
+ * g_simple_async_result_complete_in_idle() to deliver the result.
  *
  * To set the results of an asynchronous function,
  * g_simple_async_result_set_op_res_gpointer(),
@@ -9021,11 +9026,13 @@
  * Eventually, you will call a method such as
  * g_task_return_pointer() or g_task_return_error(), which will
  * save the value you give it and then invoke the task's callback
- * function (waiting until the next iteration of the main
- * loop first, if necessary). The caller will pass the #GTask back
- * to the operation's finish function (as a #GAsyncResult), and
- * you can use g_task_propagate_pointer() or the like to extract
- * the return value.
+ * function in the
+ * [thread-default main context][g-main-context-push-thread-default]
+ * where it was created (waiting until the next iteration of the main
+ * loop first, if necessary). The caller will pass the #GTask back to
+ * the operation's finish function (as a #GAsyncResult), and you can
+ * can use g_task_propagate_pointer() or the like to extract the
+ * return value.
  *
  * Here is an example for using GTask as a GAsyncResult:
  * |[<!-- language="C" -->
@@ -9264,9 +9271,10 @@
  * ## Asynchronous operations from synchronous ones
  *
  * You can use g_task_run_in_thread() to turn a synchronous
- * operation into an asynchronous one, by running it in a thread
- * which will then dispatch the result back to the caller's
- * #GMainContext when it completes.
+ * operation into an asynchronous one, by running it in a thread.
+ * When it completes, the result will be dispatched to the
+ * [thread-default main context][g-main-context-push-thread-default]
+ * where the #GTask was created.
  *
  * Running a task in a thread:
  *   |[<!-- language="C" -->
@@ -9478,7 +9486,7 @@
  *   whether the task's callback can be invoked directly, or
  *   if it needs to be sent to another #GMainContext, or delayed
  *   until the next iteration of the current #GMainContext.)
- * - The "finish" functions for #GTask-based operations are generally
+ * - The "finish" functions for #GTask based operations are generally
  *   much simpler than #GSimpleAsyncResult ones, normally consisting
  *   of only a single call to g_task_propagate_pointer() or the like.
  *   Since g_task_propagate_pointer() "steals" the return value from
@@ -12500,7 +12508,7 @@
 
 /**
  * g_app_info_create_from_commandline:
- * @commandline: the commandline to use
+ * @commandline: (type filename): the commandline to use
  * @application_name: (nullable): the application name, or %NULL to use @commandline
  * @flags: flags that can specify details of the created #GAppInfo
  * @error: a #GError location to store the error occurring, %NULL to ignore.
@@ -12549,9 +12557,9 @@
  *
  * Checks if two #GAppInfos are equal.
  *
- * Note that the check <em>may not</em> compare each individual field, and
- * only does an identity check. In case detecting changes in the contents
- * is needed, program code must additionally compare relevant fields.
+ * Note that the check <emphasis>may not</emphasis> compare each individual
+ * field, and only does an identity check. In case detecting changes in the
+ * contents is needed, program code must additionally compare relevant fields.
  *
  * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise.
  */
@@ -12750,11 +12758,11 @@
  * g_app_info_launch:
  * @appinfo: a #GAppInfo
  * @files: (nullable) (element-type GFile): a #GList of #GFile objects
- * @launch_context: (nullable): a #GAppLaunchContext or %NULL
+ * @context: (nullable): a #GAppLaunchContext or %NULL
  * @error: a #GError
  *
  * Launches the application. Passes @files to the launched application
- * as arguments, using the optional @launch_context to get information
+ * as arguments, using the optional @context to get information
  * about the details of the launcher (like what screen it is on).
  * On error, @error will be set accordingly.
  *
@@ -12779,7 +12787,7 @@
  * process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`,
  * should it be inherited by further processes. The `DISPLAY` and
  * `DESKTOP_STARTUP_ID` environment variables are also set, based
- * on information provided in @launch_context.
+ * on information provided in @context.
  *
  * Returns: %TRUE on successful launch, %FALSE otherwise.
  */
@@ -12788,7 +12796,7 @@
 /**
  * g_app_info_launch_default_for_uri:
  * @uri: the uri to show
- * @launch_context: (nullable): an optional #GAppLaunchContext
+ * @context: (nullable): an optional #GAppLaunchContext
  * @error: (nullable): return location for an error, or %NULL
  *
  * Utility function that launches the default application
@@ -12804,7 +12812,7 @@
  * g_app_info_launch_default_for_uri_async:
  * @uri: the uri to show
  * @context: (nullable): an optional #GAppLaunchContext
- * cancellable: (nullable): a #GCancellable
+ * @cancellable: (nullable): a #GCancellable
  * @callback: (nullable): a #GASyncReadyCallback to call when the request is done
  * @user_data: (nullable): data to pass to @callback
  *
@@ -12835,11 +12843,11 @@
  * g_app_info_launch_uris:
  * @appinfo: a #GAppInfo
  * @uris: (nullable) (element-type utf8): a #GList containing URIs to launch.
- * @launch_context: (nullable): a #GAppLaunchContext or %NULL
+ * @context: (nullable): a #GAppLaunchContext or %NULL
  * @error: a #GError
  *
  * Launches the application. This passes the @uris to the launched application
- * as arguments, using the optional @launch_context to get information
+ * as arguments, using the optional @context to get information
  * about the details of the launcher (like what screen it is on).
  * On error, @error will be set accordingly.
  *
@@ -12991,8 +12999,8 @@
  * This is a %NULL-terminated array of strings, where each string has
  * the form `KEY=VALUE`.
  *
- * Returns: (array zero-terminated=1) (transfer full): the
- *     child's environment
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
+ *     the child's environment
  * Since: 2.32
  */
 
@@ -13037,8 +13045,8 @@
 /**
  * g_app_launch_context_setenv:
  * @context: a #GAppLaunchContext
- * @variable: the environment variable to set
- * @value: the value for to set the variable to.
+ * @variable: (type filename): the environment variable to set
+ * @value: (type filename): the value for to set the variable to.
  *
  * Arranges for @variable to be set to @value in the child's
  * environment when @context is used to launch an application.
@@ -13050,7 +13058,7 @@
 /**
  * g_app_launch_context_unsetenv:
  * @context: a #GAppLaunchContext
- * @variable: the environment variable to remove
+ * @variable: (type filename): the environment variable to remove
  *
  * Arranges for @variable to be unset in the child's environment
  * when @context is used to launch an application.
@@ -13223,7 +13231,7 @@
 /**
  * g_application_command_line_create_file_for_arg:
  * @cmdline: a #GApplicationCommandLine
- * @arg: an argument from @cmdline
+ * @arg: (type filename): an argument from @cmdline
  *
  * Creates a #GFile corresponding to a filename that was given as part
  * of the invocation of @cmdline.
@@ -13254,8 +13262,8 @@
  * The return value is %NULL-terminated and should be freed using
  * g_strfreev().
  *
- * Returns: (array length=argc) (transfer full): the string array
- * containing the arguments (the argv)
+ * Returns: (array length=argc) (element-type filename) (transfer full):
+ *      the string array containing the arguments (the argv)
  * Since: 2.28
  */
 
@@ -13298,8 +13306,8 @@
  * See g_application_command_line_getenv() if you are only interested
  * in the value of a single environment variable.
  *
- * Returns: (array zero-terminated=1) (transfer none): the environment
- * strings, or %NULL if they were not sent
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer none):
+ *     the environment strings, or %NULL if they were not sent
  * Since: 2.28
  */
 
@@ -13387,7 +13395,7 @@
 /**
  * g_application_command_line_getenv:
  * @cmdline: a #GApplicationCommandLine
- * @name: the environment variable to get
+ * @name: (type filename): the environment variable to get
  *
  * Gets the value of a particular environment variable of the command
  * line invocation, as would be returned by g_getenv().  The strings may
@@ -13818,7 +13826,8 @@
  * g_application_run:
  * @application: a #GApplication
  * @argc: the argc from main() (or 0 if @argv is %NULL)
- * @argv: (array length=argc) (nullable): the argv from main(), or %NULL
+ * @argv: (array length=argc) (element-type filename) (nullable):
+ *     the argv from main(), or %NULL
  *
  * Runs the application.
  *
@@ -14389,7 +14398,7 @@
  *
  * Finishes an asynchronous read.
  *
- * Returns: a #gssize of the read stream, or %-1 on an error.
+ * Returns: a #gssize of the read stream, or `-1` on an error.
  */
 
 
@@ -14964,7 +14973,7 @@
 /**
  * g_cancellable_disconnect:
  * @cancellable: (nullable): A #GCancellable or %NULL.
- * @handler_id: Handler id of the handler to be disconnected, or %0.
+ * @handler_id: Handler id of the handler to be disconnected, or `0`.
  *
  * Disconnects a handler from a cancellable instance similar to
  * g_signal_handler_disconnect().  Additionally, in the event that a
@@ -14978,7 +14987,7 @@
  * signal handler is removed. See #GCancellable::cancelled for
  * details on how to use this.
  *
- * If @cancellable is %NULL or @handler_id is %0 this function does
+ * If @cancellable is %NULL or @handler_id is `0` this function does
  * nothing.
  *
  * Since: 2.22
@@ -16524,10 +16533,10 @@
  * Escape @string so it can appear in a D-Bus address as the value
  * part of a key-value pair.
  *
- * For instance, if @string is "/run/bus-for-:0",
- * this function would return "/run/bus-for-%3A0",
+ * For instance, if @string is `/run/bus-for-:0`,
+ * this function would return `/run/bus-for-%3A0`,
  * which could be used in a D-Bus address like
- * "unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0".
+ * `unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0`.
  *
  * Returns: (transfer full): a copy of @string with all
  *     non-optionally-escaped bytes escaped
@@ -21880,7 +21889,7 @@
  *
  * Sets the certificate database that is used to verify peer certificates.
  * This is set to the default database by default. See
- * g_dtls_backend_get_default_database(). If set to %NULL, then
+ * g_tls_backend_get_default_database(). If set to %NULL, then
  * peer certificate validation will always set the
  * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning
  * #GDtlsConnection::accept-certificate will always be emitted on
@@ -24924,8 +24933,24 @@
 
 
 /**
+ * g_file_new_build_filename:
+ * @first_element: (type filename): the first element in the path
+ * @...: remaining elements in path, terminated by %NULL
+ *
+ * Constructs a #GFile from a series of elements using the correct
+ * separator for filenames.
+ *
+ * Using this function is equivalent to calling g_build_filename(),
+ * followed by g_file_new_for_path() on the result.
+ *
+ * Returns: (transfer full): a new #GFile
+ * Since: 2.56
+ */
+
+
+/**
  * g_file_new_for_commandline_arg:
- * @arg: a command line string
+ * @arg: (type filename): a command line string
  *
  * Creates a #GFile with the given argument from the command line.
  * The value of @arg can be either a URI, an absolute path or a
@@ -24949,7 +24974,7 @@
 
 /**
  * g_file_new_for_commandline_arg_and_cwd:
- * @arg: a command line string
+ * @arg: (type filename): a command line string
  * @cwd: (type filename): the current working directory of the commandline
  *
  * Creates a #GFile with the given argument from the command line.
@@ -32705,7 +32730,8 @@
  * g_seekable_can_truncate:
  * @seekable: a #GSeekable.
  *
- * Tests if the stream can be truncated.
+ * Tests if the length of the stream can be adjusted with
+ * g_seekable_truncate().
  *
  * Returns: %TRUE if the stream can be truncated, %FALSE otherwise.
  */
@@ -32754,12 +32780,14 @@
 /**
  * g_seekable_truncate: (virtual truncate_fn)
  * @seekable: a #GSeekable.
- * @offset: a #goffset.
+ * @offset: new length for @seekable, in bytes.
  * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore.
  * @error: a #GError location to store the error occurring, or %NULL to
  * ignore.
  *
- * Truncates a stream with a given #offset.
+ * Sets the length of the stream to @offset. If the stream was previously
+ * larger than @offset, the extra data is discarded. If the stream was
+ * previouly shorter than @offset, it is extended with NUL ('\0') bytes.
  *
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
@@ -32984,7 +33012,7 @@
  * a boolean property by that name). See g_settings_bind_writable()
  * for more details about writable bindings.
  *
- * Note that the lifecycle of the binding is tied to the object,
+ * Note that the lifecycle of the binding is tied to @object,
  * and that you can have only one binding per object property.
  * If you bind the same property twice on the same object, the second
  * binding overrides the first one.
@@ -33013,7 +33041,7 @@
  * The binding uses the provided mapping functions to map between
  * settings and property values.
  *
- * Note that the lifecycle of the binding is tied to the object,
+ * Note that the lifecycle of the binding is tied to @object,
  * and that you can have only one binding per object property.
  * If you bind the same property twice on the same object, the second
  * binding overrides the first one.
@@ -33043,7 +33071,7 @@
  * value as it passes from the setting to the object, i.e. @property
  * will be set to %TRUE if the key is not writable.
  *
- * Note that the lifecycle of the binding is tied to the object,
+ * Note that the lifecycle of the binding is tied to @object,
  * and that you can have only one binding per object property.
  * If you bind the same property twice on the same object, the second
  * binding overrides the first one.
@@ -36508,12 +36536,45 @@
  * in RFC 4604 is used. Note that on older platforms this may fail
  * with a %G_IO_ERROR_NOT_SUPPORTED error.
  *
+ * To bind to a given source-specific multicast address, use
+ * g_socket_join_multicast_group_ssm() instead.
+ *
  * Returns: %TRUE on success, %FALSE on error.
  * Since: 2.32
  */
 
 
 /**
+ * g_socket_join_multicast_group_ssm:
+ * @socket: a #GSocket.
+ * @group: a #GInetAddress specifying the group address to join.
+ * @source_specific: (nullable): a #GInetAddress specifying the
+ * source-specific multicast address or %NULL to ignore.
+ * @iface: (nullable): Name of the interface to use, or %NULL
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Registers @socket to receive multicast messages sent to @group.
+ * @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have
+ * been bound to an appropriate interface and port with
+ * g_socket_bind().
+ *
+ * If @iface is %NULL, the system will automatically pick an interface
+ * to bind to based on @group.
+ *
+ * If @source_specific is not %NULL, use source-specific multicast as
+ * defined in RFC 4604. Note that on older platforms this may fail
+ * with a %G_IO_ERROR_NOT_SUPPORTED error.
+ *
+ * Note that this function can be called multiple times for the same
+ * @group with different @source_specific in order to receive multicast
+ * packets from more than one source.
+ *
+ * Returns: %TRUE on success, %FALSE on error.
+ * Since: 2.56
+ */
+
+
+/**
  * g_socket_leave_multicast_group:
  * @socket: a #GSocket.
  * @group: a #GInetAddress specifying the group address to leave.
@@ -36528,12 +36589,36 @@
  * @socket remains bound to its address and port, and can still receive
  * unicast messages after calling this.
  *
+ * To unbind to a given source-specific multicast address, use
+ * g_socket_leave_multicast_group_ssm() instead.
+ *
  * Returns: %TRUE on success, %FALSE on error.
  * Since: 2.32
  */
 
 
 /**
+ * g_socket_leave_multicast_group_ssm:
+ * @socket: a #GSocket.
+ * @group: a #GInetAddress specifying the group address to leave.
+ * @source_specific: (nullable): a #GInetAddress specifying the
+ * source-specific multicast address or %NULL to ignore.
+ * @iface: (nullable): Name of the interface to use, or %NULL
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Removes @socket from the multicast group defined by @group, @iface,
+ * and @source_specific (which must all have the same values they had
+ * when you joined the group).
+ *
+ * @socket remains bound to its address and port, and can still receive
+ * unicast messages after calling this.
+ *
+ * Returns: %TRUE on success, %FALSE on error.
+ * Since: 2.56
+ */
+
+
+/**
  * g_socket_listen:
  * @socket: a #GSocket.
  * @error: #GError for error reporting, or %NULL to ignore.
@@ -37998,7 +38083,7 @@
 /**
  * g_subprocess_launcher_getenv:
  * @self: a #GSubprocess
- * @variable: the environment variable to get
+ * @variable: (type filename): the environment variable to get
  *
  * Returns the value of the environment variable @variable in the
  * environment of processes launched from this launcher.
@@ -38006,7 +38091,8 @@
  * On UNIX, the returned string can be an arbitrary byte string.
  * On Windows, it will be UTF-8.
  *
- * Returns: the value of the environment variable, %NULL if unset
+ * Returns: (type filename): the value of the environment variable,
+ *     %NULL if unset
  * Since: 2.40
  */
 
@@ -38068,7 +38154,8 @@
 /**
  * g_subprocess_launcher_set_environ:
  * @self: a #GSubprocess
- * @env: (array zero-terminated=1) (transfer none): the replacement environment
+ * @env: (array zero-terminated=1) (element-type filename) (transfer none):
+ *     the replacement environment
  *
  * Replace the entire environment of processes launched from this
  * launcher with the given 'environ' variable.
@@ -38184,8 +38271,9 @@
 /**
  * g_subprocess_launcher_setenv:
  * @self: a #GSubprocess
- * @variable: the environment variable to set, must not contain '='
- * @value: the new value for the variable
+ * @variable: (type filename): the environment variable to set,
+ *     must not contain '='
+ * @value: (type filename): the new value for the variable
  * @overwrite: whether to change the variable if it already exists
  *
  * Sets the environment variable @variable in the environment of
@@ -38216,7 +38304,7 @@
 /**
  * g_subprocess_launcher_spawnv:
  * @self: a #GSubprocessLauncher
- * @argv: (array zero-terminated=1) (element-type utf8): Command line arguments
+ * @argv: (array zero-terminated=1) (element-type filename): Command line arguments
  * @error: Error
  *
  * Creates a #GSubprocess given a provided array of arguments.
@@ -38331,7 +38419,8 @@
 /**
  * g_subprocess_launcher_unsetenv:
  * @self: a #GSubprocess
- * @variable: the environment variable to unset, must not contain '='
+ * @variable: (type filename): the environment variable to unset,
+ *     must not contain '='
  *
  * Removes the environment variable @variable from the environment of
  * processes launched from this launcher.
@@ -38366,7 +38455,7 @@
 
 /**
  * g_subprocess_newv: (rename-to g_subprocess_new)
- * @argv: (array zero-terminated=1) (element-type utf8): commandline arguments for the subprocess
+ * @argv: (array zero-terminated=1) (element-type filename): commandline arguments for the subprocess
  * @flags: flags that define the behaviour of the subprocess
  * @error: (nullable): return location for an error, or %NULL
  *
@@ -40094,7 +40183,7 @@
  * @error: a #GError pointer, or %NULL
  *
  * Finish an asynchronous lookup of a certificate by its handle. See
- * g_tls_database_lookup_certificate_handle() for more information.
+ * g_tls_database_lookup_certificate_by_handle() for more information.
  *
  * If the handle is no longer valid, or does not point to a certificate in
  * this database, then %NULL will be returned.
@@ -40232,7 +40321,7 @@
  * adding any missing certificates to the chain.
  *
  * @chain is a chain of #GTlsCertificate objects each pointing to the next
- * certificate in the chain by its %issuer property. The chain may initially
+ * 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
@@ -41198,6 +41287,41 @@
 
 
 /**
+ * g_unix_is_system_device_path:
+ * @device_path: a device path, e.g. `/dev/loop0` or `nfsd`
+ *
+ * Determines if @device_path is considered a block device path which is only
+ * used in implementation of the OS. This is primarily used for hiding
+ * mounted volumes that are intended as APIs for programs to read, and system
+ * administrators at a shell; rather than something that should, for example,
+ * appear in a GUI. For example, the Linux `/proc` filesystem.
+ *
+ * The list of device paths considered ‘system’ ones may change over time.
+ *
+ * Returns: %TRUE if @device_path is considered an implementation detail of
+ *    the OS.
+ * Since: 2.56
+ */
+
+
+/**
+ * g_unix_is_system_fs_type:
+ * @fs_type: a file system type, e.g. `procfs` or `tmpfs`
+ *
+ * Determines if @fs_type is considered a type of file system which is only
+ * used in implementation of the OS. This is primarily used for hiding
+ * mounted volumes that are intended as APIs for programs to read, and system
+ * administrators at a shell; rather than something that should, for example,
+ * appear in a GUI. For example, the Linux `/proc` filesystem.
+ *
+ * The list of file system types considered ‘system’ ones may change over time.
+ *
+ * Returns: %TRUE if @fs_type is considered an implementation detail of the OS.
+ * Since: 2.56
+ */
+
+
+/**
  * g_unix_mount_at:
  * @mount_path: (type filename): path for a possible unix mount.
  * @time_read: (out) (optional): guint64 to contain a timestamp.
@@ -41363,7 +41487,12 @@
  * g_unix_mount_is_system_internal:
  * @mount_entry: a #GUnixMount.
  *
- * Checks if a unix mount is a system path.
+ * Checks if a Unix mount is a system mount. This is the Boolean OR of
+ * g_unix_is_system_fs_type(), g_unix_is_system_device_path() and
+ * g_unix_is_mount_path_system_internal() on @mount_entry’s properties.
+ *
+ * The definition of what a ‘system’ mount entry is may change over time as new
+ * file system types and device paths are ignored.
  *
  * Returns: %TRUE if the unix mount is for a system path.
  */
@@ -42062,7 +42191,7 @@
  * then the expression
  * |[<!-- language="C" -->
  *   (g_file_has_prefix (volume_activation_root, mount_root) ||
- *       g_file_equal (volume_activation_root, mount_root))
+ *    g_file_equal (volume_activation_root, mount_root))
  * ]|
  * will always be %TRUE.
  *
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index ce126e04..23509cf5 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -532,6 +532,8 @@
  *     suffixes. IEC units should only be used for reporting things with
  *     a strong "power of 2" basis, like RAM sizes or RAID stripe sizes.
  *     Network and storage sizes should be reported in the normal SI units.
+ * @G_FORMAT_SIZE_BITS: set the size as a quantity in bits, rather than
+ *     bytes, and return units in bits. For example, ‘Mb’ rather than ‘MB’.
  *
  * Flags to modify the format of the string returned by g_format_size_full().
  */
@@ -2016,7 +2018,7 @@
  *
  * Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(),
  * which is deprecated. g_test_trap_subprocess() uses
- * #GTestTrapSubprocessFlags.
+ * #GTestSubprocessFlags.
  */
 
 
@@ -3207,6 +3209,8 @@
 
 /**
  * G_GNUC_CHECK_VERSION:
+ * @major: major version to check against
+ * @minor: minor version to check against
  *
  * Expands to a a check for a compiler with __GNUC__ defined and a version
  * greater than or equal to the major and minor numbers provided. For example,
@@ -4569,7 +4573,7 @@
  * A macro to assist with the static initialisation of a #GPrivate.
  *
  * This macro is useful for the case that a #GDestroyNotify function
- * should be associated the key.  This is needed when the key will be
+ * should be associated with the key.  This is needed when the key will be
  * used to point at memory that should be deallocated when the thread
  * exits.
  *
@@ -5491,7 +5495,6 @@
  * ## Checklist for Application Writers
  *
  * This section is a practical summary of the detailed
- *  
  * things to do to make sure your applications process file
  * name encodings correctly.
  *
@@ -6861,6 +6864,58 @@
  * multiple groups with the same name; they are merged together.
  * Another difference is that keys and group names in key files are not
  * restricted to ASCII characters.
+ *
+ * Here is an example of loading a key file and reading a value:
+ * |[<!-- language="C" -->
+ * g_autoptr(GError) error = NULL;
+ * g_autoptr(GKeyFile) key_file = g_key_file_new ();
+ *
+ * if (!g_key_file_load_from_file (key_file, "key-file.ini", flags, &error))
+ *   {
+ *     if (!g_error_matches (error, G_FILE_ERROR, G_FILE_ERROR_NOENT))
+ *       g_warning ("Error loading key file: %s", error->message);
+ *     return;
+ *   }
+ *
+ * g_autofree gchar *val = g_key_file_get_string (key_file, "Group Name", "SomeKey", &error);
+ * if (val == NULL &&
+ *     !g_error_matches (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_KEY_NOT_FOUND))
+ *   {
+ *     g_warning ("Error finding key in key file: %s", error->message);
+ *     return;
+ *   }
+ * else if (val == NULL)
+ *   {
+ *     // Fall back to a default value.
+ *     val = g_strdup ("default-value");
+ *   }
+ * ]|
+ *
+ * Here is an example of creating and saving a key file:
+ * |[<!-- language="C" -->
+ * g_autoptr(GKeyFile) key_file = g_key_file_new ();
+ * const gchar *val = …;
+ * g_autoptr(GError) error = NULL;
+ *
+ * g_key_file_set_string (key_file, "Group Name", "SomeKey", val);
+ *
+ * // Save as a file.
+ * if (!g_key_file_save_to_file (key_file, "key-file.ini", &error))
+ *   {
+ *     g_warning ("Error saving key file: %s", error->message);
+ *     return;
+ *   }
+ *
+ * // Or store to a GBytes for use elsewhere.
+ * gsize data_len;
+ * g_autofree guint8 *data = (guint8 *) g_key_file_to_data (key_file, &data_len, &error);
+ * if (data == NULL)
+ *   {
+ *     g_warning ("Error saving key file: %s", error->message);
+ *     return;
+ *   }
+ * g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len);
+ * ]|
  */
 
 
@@ -11595,6 +11650,20 @@
 
 
 /**
+ * g_build_filename_valist:
+ * @first_element: (type filename): the first element in the path
+ * @args: va_list of remaining elements in path
+ *
+ * Behaves exactly like g_build_filename(), but takes the path elements
+ * as a va_list. This function is mainly meant for language bindings.
+ *
+ * Returns: (type filename): a newly-allocated string that must be freed
+ *     with g_free().
+ * Since: 2.56
+ */
+
+
+/**
  * g_build_filenamev:
  * @args: (array zero-terminated=1) (element-type filename): %NULL-terminated
  *     array of strings containing the path elements.
@@ -11975,7 +12044,7 @@
 /**
  * g_bytes_new_static: (skip)
  * @data: (transfer full) (array length=size) (element-type guint8) (nullable):
- *           the data to be used for the bytes
+ *        the data to be used for the bytes
  * @size: the size of @data
  *
  * Creates a new #GBytes from static data.
@@ -11991,7 +12060,7 @@
 /**
  * g_bytes_new_take:
  * @data: (transfer full) (array length=size) (element-type guint8) (nullable):
- *           the data to be used for the bytes
+ *        the data to be used for the bytes
  * @size: the size of @data
  *
  * Creates a new #GBytes from @data.
@@ -12015,7 +12084,7 @@
 /**
  * g_bytes_new_with_free_func: (skip)
  * @data: (array length=size) (element-type guint8) (nullable):
- *           the data to be used for the bytes
+ *        the data to be used for the bytes
  * @size: the size of @data
  * @free_func: the function to call to release the data
  * @user_data: data to pass to @free_func
@@ -12248,6 +12317,8 @@
  * g_spawn_close_pid() in the callback function for the source.
  *
  * GLib supports only a single callback per process id.
+ * On POSIX platforms, the same restrictions mentioned for
+ * g_child_watch_source_new() apply to this function.
  *
  * This internally creates a main loop source using
  * g_child_watch_source_new() and attaches it to the main loop context
@@ -12286,6 +12357,8 @@
  * in the callback function for the source.
  *
  * GLib supports only a single callback per process id.
+ * On POSIX platforms, the same restrictions mentioned for
+ * g_child_watch_source_new() apply to this function.
  *
  * This internally creates a main loop source using
  * g_child_watch_source_new() and attaches it to the main loop context
@@ -12316,14 +12389,24 @@
  * source is still active. Typically, you will want to call
  * g_spawn_close_pid() in the callback function for the source.
  *
- * Note further that using g_child_watch_source_new() is not
- * compatible with calling `waitpid` with a nonpositive first
- * argument in the application. Calling waitpid() for individual
- * pids will still work fine.
+ * On POSIX platforms, the following restrictions apply to this API
+ * due to limitations in POSIX process interfaces:
+ *
+ * * @pid must be a child of this process
+ * * @pid must be positive
+ * * the application must not call `waitpid` with a non-positive
+ *   first argument, for instance in another thread
+ * * the application must not wait for @pid to exit by any other
+ *   mechanism, including `waitpid(pid, ...)` or a second child-watch
+ *   source for the same @pid
+ * * the application must not ignore SIGCHILD
  *
- * Similarly, on POSIX platforms, the @pid passed to this function must
- * be greater than 0 (i.e. this function must wait for a specific child,
- * and cannot wait for one of many children by using a nonpositive argument).
+ * If any of those conditions are not met, this and related APIs will
+ * not work correctly. This can often be diagnosed via a GLib warning
+ * stating that `ECHILD` was received by `waitpid`.
+ *
+ * Calling `waitpid` for specific processes other than @pid remains a
+ * valid thing to do.
  *
  * Returns: the newly-created child watch source
  * Since: 2.4
@@ -12362,6 +12445,26 @@
 
 
 /**
+ * g_clear_handle_id: (skip)
+ * @tag_ptr: (not nullable): a pointer to the handler ID
+ * @clear_func: (not nullable): the function to call to clear the handler
+ *
+ * Clears a numeric handler, such as a #GSource ID.
+ *
+ * @tag_ptr must be a valid pointer to the variable holding the handler.
+ *
+ * If the ID is zero then this function does nothing.
+ * Otherwise, clear_func() is called with the ID as a parameter, and the tag is
+ * set to zero.
+ *
+ * A macro is also included that allows this function to be used without
+ * pointer casts.
+ *
+ * Since: 2.56
+ */
+
+
+/**
  * g_clear_pointer: (skip)
  * @pp: (not nullable): a pointer to a variable, struct member etc. holding a
  *    pointer
@@ -12703,8 +12806,8 @@
  * @fallback: UTF-8 string to use in place of character not
  *                present in the target encoding. (The string must be
  *                representable in the target encoding).
- *                   If %NULL, characters not in the target encoding will
- *                   be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
+ *                If %NULL, characters not in the target encoding will
+ *                be represented as Unicode escapes \uxxxx or \Uxxxxyyyy.
  * @bytes_read: location to store the number of bytes in the
  *                input string that were successfully converted, or %NULL.
  *                Even if the conversion was successful, this may be
@@ -12825,7 +12928,14 @@
  *
  * You can also make critical warnings fatal at runtime by
  * setting the `G_DEBUG` environment variable (see
- * [Running GLib Applications](glib-running.html)).
+ * [Running GLib Applications](glib-running.html)):
+ *
+ * |[
+ *   G_DEBUG=fatal-warnings gdb ./my-program
+ * ]|
+ *
+ * Any unrelated failures can be skipped over in
+ * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command.
  *
  * The message should typically *not* be translated to the
  * user's language.
@@ -15073,15 +15183,15 @@
 
 /**
  * g_environ_getenv:
- * @envp: (nullable) (array zero-terminated=1) (transfer none): an environment
- *     list (eg, as returned from g_get_environ()), or %NULL
+ * @envp: (nullable) (array zero-terminated=1) (transfer none) (element-type filename):
+ *     an environment list (eg, as returned from g_get_environ()), or %NULL
  *     for an empty environment list
- * @variable: the environment variable to get
+ * @variable: (type filename): the environment variable to get
  *
  * Returns the value of the environment variable @variable in the
  * provided list @envp.
  *
- * Returns: the value of the environment variable, or %NULL if
+ * Returns: (type filename): the value of the environment variable, or %NULL if
  *     the environment variable is not set in @envp. The returned
  *     string is owned by @envp, and will be freed if @variable is
  *     set or unset again.
@@ -15091,35 +15201,37 @@
 
 /**
  * g_environ_setenv:
- * @envp: (nullable) (array zero-terminated=1) (transfer full): an
- *     environment list that can be freed using g_strfreev() (e.g., as
+ * @envp: (nullable) (array zero-terminated=1) (element-type filename) (transfer full):
+ *     an environment list that can be freed using g_strfreev() (e.g., as
  *     returned from g_get_environ()), or %NULL for an empty
  *     environment list
- * @variable: the environment variable to set, must not contain '='
- * @value: the value for to set the variable to
+ * @variable: (type filename): the environment variable to set, must not
+ *     contain '='
+ * @value: (type filename): the value for to set the variable to
  * @overwrite: whether to change the variable if it already exists
  *
  * Sets the environment variable @variable in the provided list
  * @envp to @value.
  *
- * Returns: (array zero-terminated=1) (transfer full): the
- *     updated environment list. Free it using g_strfreev().
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
+ *     the updated environment list. Free it using g_strfreev().
  * Since: 2.32
  */
 
 
 /**
  * g_environ_unsetenv:
- * @envp: (nullable) (array zero-terminated=1) (transfer full): an environment
- *     list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()),
- *     or %NULL for an empty environment list
- * @variable: the environment variable to remove, must not contain '='
+ * @envp: (nullable) (array zero-terminated=1) (element-type filename) (transfer full):
+ *     an environment list that can be freed using g_strfreev() (e.g., as
+ *     returned from g_get_environ()), or %NULL for an empty environment list
+ * @variable: (type filename): the environment variable to remove, must not
+ *     contain '='
  *
  * Removes the environment variable @variable from the provided
  * environment @envp.
  *
- * Returns: (array zero-terminated=1) (transfer full): the
- *     updated environment list. Free it using g_strfreev().
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
+ *     the updated environment list. Free it using g_strfreev().
  * Since: 2.32
  */
 
@@ -15810,8 +15922,8 @@
  * The return value is freshly allocated and it should be freed with
  * g_strfreev() when it is no longer needed.
  *
- * Returns: (array zero-terminated=1) (transfer full): the list of
- *     environment variables
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
+ *     the list of environment variables
  * Since: 2.28
  */
 
@@ -15894,6 +16006,8 @@
  * name can be determined, a default fixed string "localhost" is
  * returned.
  *
+ * The encoding of the returned string is UTF-8.
+ *
  * Returns: the host name of the machine.
  * Since: 2.8
  */
@@ -16241,7 +16355,7 @@
 
 /**
  * g_getenv:
- * @variable: the environment variable to get
+ * @variable: (type filename): the environment variable to get
  *
  * Returns the value of an environment variable.
  *
@@ -16251,7 +16365,7 @@
  * On Windows, in case the environment variable's value contains
  * references to other environment variables, they are expanded.
  *
- * Returns: the value of the environment variable, or %NULL if
+ * Returns: (type filename): the value of the environment variable, or %NULL if
  *     the environment variable is not found. The returned string
  *     may be overwritten by the next call to g_getenv(), g_setenv()
  *     or g_unsetenv().
@@ -19580,8 +19694,9 @@
  * use cases for environment variables in GLib-using programs you want
  * the UTF-8 encoding that this function and g_getenv() provide.
  *
- * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated
- *     list of strings which must be freed with g_strfreev().
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer full):
+ *     a %NULL-terminated list of strings which must be freed with
+ *     g_strfreev().
  * Since: 2.8
  */
 
@@ -22738,7 +22853,7 @@
 
 /**
  * g_option_context_get_strict_posix:
- * @context: a #GoptionContext
+ * @context: a #GOptionContext
  *
  * Returns whether strict POSIX code is enabled.
  *
@@ -22921,7 +23036,7 @@
 
 /**
  * g_option_context_set_strict_posix:
- * @context: a #GoptionContext
+ * @context: a #GOptionContext
  * @strict_posix: the new value
  *
  * Sets strict POSIX mode.
@@ -23382,9 +23497,9 @@
  * don't want to run the full main loop.
  *
  * Each element of @fds is a #GPollFD describing a single file
- * descriptor to poll. The %fd field indicates the file descriptor,
- * and the %events field indicates the events to poll for. On return,
- * the %revents fields will be filled with the events that actually
+ * descriptor to poll. The @fd field indicates the file descriptor,
+ * and the @events field indicates the events to poll for. On return,
+ * the @revents fields will be filled with the events that actually
  * occurred.
  *
  * On POSIX systems, the file descriptors in @fds can be any sort of
@@ -23393,7 +23508,7 @@
  * Windows, the easiest solution is to construct all of your
  * #GPollFDs with g_io_channel_win32_make_pollfd().
  *
- * Returns: the number of entries in @fds whose %revents fields
+ * Returns: the number of entries in @fds whose @revents fields
  * were filled in, or 0 if the operation timed out, or -1 on error or
  * if the call was interrupted.
  * Since: 2.20
@@ -25586,7 +25701,8 @@
  * thread will block. Read locks can be taken recursively.
  *
  * It is implementation-defined how many threads are allowed to
- * hold read locks on the same lock simultaneously.
+ * hold read locks on the same lock simultaneously. If the limit is hit,
+ * or if a deadlock is detected, a critical warning will be emitted.
  *
  * Since: 2.32
  */
@@ -26688,8 +26804,9 @@
 
 /**
  * g_setenv:
- * @variable: the environment variable to set, must not contain '='.
- * @value: the value for to set the variable to.
+ * @variable: (type filename): the environment variable to set, must not
+ *     contain '='.
+ * @value: (type filename): the value for to set the variable to.
  * @overwrite: whether to change the variable if it already exists.
  *
  * Sets an environment variable. On UNIX, both the variable's name and
@@ -26719,10 +26836,10 @@
 
 /**
  * g_shell_parse_argv:
- * @command_line: command line to parse
+ * @command_line: (type filename): command line to parse
  * @argcp: (out) (optional): return location for number of args
- * @argvp: (out) (optional) (array length=argcp zero-terminated=1): return
- *   location for array of args
+ * @argvp: (out) (optional) (array length=argcp zero-terminated=1) (element-type filename):
+ *   return location for array of args
  * @error: (optional): return location for error
  *
  * Parses a command line into an argument vector, in much the same way
@@ -26741,7 +26858,7 @@
 
 /**
  * g_shell_quote:
- * @unquoted_string: a literal string
+ * @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
@@ -26750,13 +26867,13 @@
  * quoting style used is undefined (single or double quotes may be
  * used).
  *
- * Returns: quoted string
+ * Returns: (type filename): quoted string
  */
 
 
 /**
  * g_shell_unquote:
- * @quoted_string: shell-quoted string
+ * @quoted_string: (type filename): shell-quoted string
  * @error: error return location or NULL
  *
  * Unquotes a string as the shell (/bin/sh) would. Only handles
@@ -26781,7 +26898,7 @@
  * be escaped with backslash. Otherwise double quotes preserve things
  * literally.
  *
- * Returns: an unquoted string
+ * Returns: (type filename): an unquoted string
  */
 
 
@@ -28158,9 +28275,12 @@
 
 /**
  * g_spawn_async:
- * @working_directory: (type filename) (nullable): child's current working directory, or %NULL to inherit parent's
- * @argv: (array zero-terminated=1): child's argument vector
- * @envp: (array zero-terminated=1) (nullable): child's environment, or %NULL to inherit parent's
+ * @working_directory: (type filename) (nullable): child's current working
+ *     directory, or %NULL to inherit parent's
+ * @argv: (array zero-terminated=1) (element-type filename):
+ *     child's argument vector
+ * @envp: (array zero-terminated=1) (element-type filename) (nullable):
+ *     child's environment, or %NULL to inherit parent's
  * @flags: flags from #GSpawnFlags
  * @child_setup: (scope async) (nullable): function to run in the child just before exec()
  * @user_data: (closure): user data for @child_setup
@@ -28176,7 +28296,7 @@
  * 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.
+ * #GAppLaunchContext, or set the %DISPLAY environment variable.
  *
  * Note that the returned @child_pid on Windows is a handle to the child
  * process and not its identifier. Process handles and process identifiers
@@ -28188,9 +28308,13 @@
 
 /**
  * g_spawn_async_with_pipes:
- * @working_directory: (type filename) (nullable): child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding
- * @argv: (array zero-terminated=1): child's argument vector, in the GLib file name encoding
- * @envp: (array zero-terminated=1) (nullable): child's environment, or %NULL to inherit parent's, in the GLib file name encoding
+ * @working_directory: (type filename) (nullable): child's current working
+ *     directory, or %NULL to inherit parent's, in the GLib file name encoding
+ * @argv: (array zero-terminated=1) (element-type filename): child's argument
+ *     vector, in the GLib file name encoding
+ * @envp: (array zero-terminated=1) (element-type filename) (nullable):
+ *     child's environment, or %NULL to inherit parent's, in the GLib file
+ *     name encoding
  * @flags: flags from #GSpawnFlags
  * @child_setup: (scope async) (nullable): function to run in the child just before exec()
  * @user_data: (closure): user data for @child_setup
@@ -28349,7 +28473,7 @@
  * 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.
+ * #GAppLaunchContext, or set the %DISPLAY environment variable.
  *
  * Returns: %TRUE on success, %FALSE if an error was set
  */
@@ -28416,7 +28540,7 @@
 
 /**
  * g_spawn_command_line_async:
- * @command_line: a command line
+ * @command_line: (type filename): a command line
  * @error: return location for errors
  *
  * A simple version of g_spawn_async() that parses a command line with
@@ -28435,7 +28559,7 @@
 
 /**
  * g_spawn_command_line_sync:
- * @command_line: a command line
+ * @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()
@@ -28470,9 +28594,12 @@
 
 /**
  * g_spawn_sync:
- * @working_directory: (type filename) (nullable): child's current working directory, or %NULL to inherit parent's
- * @argv: (array zero-terminated=1): child's argument vector
- * @envp: (array zero-terminated=1) (nullable): child's environment, or %NULL to inherit parent's
+ * @working_directory: (type filename) (nullable): child's current working
+ *     directory, or %NULL to inherit parent's
+ * @argv: (array zero-terminated=1) (element-type filename):
+ *     child's argument vector
+ * @envp: (array zero-terminated=1) (element-type filename) (nullable):
+ *     child's environment, or %NULL to inherit parent's
  * @flags: flags from #GSpawnFlags
  * @child_setup: (scope async) (nullable): function to run in the child just before exec()
  * @user_data: (closure): user data for @child_setup
@@ -28491,7 +28618,8 @@
  * the child is stored there; see the documentation of
  * g_spawn_check_exit_status() for how to use and interpret this.
  * Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in
- * @flags.
+ * @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.
@@ -30684,7 +30812,6 @@
  * g_test_init(). See the g_test_run() documentation for more
  * information on the order that tests are run in.
  *
- *
  * g_test_run_suite() or g_test_run() may only be called once
  * in a program.
  *
@@ -33117,7 +33244,7 @@
  * g_unix_fd_add:
  * @fd: a file descriptor
  * @condition: IO conditions to watch for on @fd
- * @function: a #GPollFDFunc
+ * @function: a #GUnixFDSourceFunc
  * @user_data: data to pass to @function
  *
  * Sets a function to be called when the IO condition, as specified by
@@ -33298,7 +33425,8 @@
 
 /**
  * g_unsetenv:
- * @variable: the environment variable to remove, must not contain '='
+ * @variable: (type filename): the environment variable to remove, must
+ *     not contain '='
  *
  * Removes an environment variable from the environment.
  *
@@ -37292,7 +37420,14 @@
  *
  * You can make warnings fatal at runtime by setting the `G_DEBUG`
  * environment variable (see
- * [Running GLib Applications](glib-running.html)).
+ * [Running GLib Applications](glib-running.html)):
+ *
+ * |[
+ *   G_DEBUG=fatal-warnings gdb ./my-program
+ * ]|
+ *
+ * Any unrelated failures can be skipped over in
+ * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command.
  *
  * If g_log_default_handler() is used as the log handler function,
  * a newline character will automatically be appended to @..., and
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c
index 4eaeb195..f94bdb49 100644
--- a/gir/gobject-2.0.c
+++ b/gir/gobject-2.0.c
@@ -671,7 +671,7 @@
  * 4. Invocation of user provided signal handlers (where the @after flag is set)
  *
  * 5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
- *  
+ *
  * The user-provided signal handlers are called in the order they were
  * connected in.
  *
@@ -3634,7 +3634,7 @@
  *
  * Gets the default value of @pspec as a pointer to a #GValue.
  *
- * The #GValue will remain value for the life of @pspec.
+ * The #GValue will remain valid for the life of @pspec.
  *
  * Returns: a pointer to a #GValue which must not be modified
  * Since: 2.38