gir: Update annotations from glib git master

2 files changed, 381 insertions, 156 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 3f8aa5d7..db7e25b5 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -7593,6 +7593,13 @@
  * set to the full path to the gdk-pixbuf-pixdata executable; otherwise the resource compiler will
  * abort.
  *
+ * `json-stripblanks` which will use the `json-glib-format` command to strip
+ * ignorable whitespace from the JSON file. For this to work, the
+ * `JSON_GLIB_FORMAT` environment variable must be set to the full path to the
+ * `json-glib-format` executable, or it must be in the `PATH`;
+ * otherwise the preprocessing step is skipped. In addition, at least version
+ * 1.6 of `json-glib-format` is required.
+ *
  * Resource files will be exported in the GResource namespace using the
  * combination of the given `prefix` and the filename from the `file` element.
  * The `alias` attribute can be used to alter the filename to expose them at a
@@ -21487,6 +21494,21 @@
  * Deletes a file. If the @file is a directory, it will only be
  * deleted if it is empty. This has the same semantics as g_unlink().
  *
+ * If @file doesn’t exist, %G_IO_ERROR_NOT_FOUND will be returned. This allows
+ * for deletion to be implemented avoiding
+ * [time-of-check to time-of-use races](https://en.wikipedia.org/wiki/Time-of-check_to_time-of-use):
+ * |[
+ * g_autoptr(GError) local_error = NULL;
+ * if (!g_file_delete (my_file, my_cancellable, &local_error) &&
+ *     !g_error_matches (local_error, G_IO_ERROR, G_IO_ERROR_NOT_FOUND))
+ *   {
+ *     // deletion failed for some reason other than the file not existing:
+ *     // so report the error
+ *     g_warning ("Failed to delete %s: %s",
+ *                g_file_peek_path (my_file), local_error->message);
+ *   }
+ * ]|
+ *
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
  * was cancelled, the error %G_IO_ERROR_CANCELLED will be returned.
@@ -25188,7 +25210,9 @@
  * Sends @file to the "Trashcan", if possible. This is similar to
  * deleting it, but the user can recover it before emptying the trashcan.
  * Not all file systems support trashing, so this call can return the
- * %G_IO_ERROR_NOT_SUPPORTED error.
+ * %G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the `x-gvfs-notrash` unix
+ * mount option can be used to disable g_file_trash() support for certain
+ * mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case.
  *
  * If @cancellable is not %NULL, then the operation can be cancelled by
  * triggering the cancellable object from another thread. If the operation
@@ -36317,8 +36341,8 @@
 /**
  * g_socket_receive:
  * @socket: a #GSocket
- * @buffer: (array length=size) (element-type guint8): a buffer to
- *     read data into (which should be at least @size bytes long).
+ * @buffer: (array length=size) (element-type guint8) (out caller-allocates):
+ *     a buffer to read data into (which should be at least @size bytes long).
  * @size: the number of bytes you want to read from the socket
  * @cancellable: (nullable): a %GCancellable or %NULL
  * @error: #GError for error reporting, or %NULL to ignore.
@@ -36358,8 +36382,8 @@
  * @socket: a #GSocket
  * @address: (out) (optional): a pointer to a #GSocketAddress
  *     pointer, or %NULL
- * @buffer: (array length=size) (element-type guint8): a buffer to
- *     read data into (which should be at least @size bytes long).
+ * @buffer: (array length=size) (element-type guint8) (out caller-allocates):
+ *     a buffer to read data into (which should be at least @size bytes long).
  * @size: the number of bytes you want to read from the socket
  * @cancellable: (nullable): a %GCancellable or %NULL
  * @error: #GError for error reporting, or %NULL to ignore.
@@ -36533,8 +36557,8 @@
 /**
  * g_socket_receive_with_blocking:
  * @socket: a #GSocket
- * @buffer: (array length=size) (element-type guint8): a buffer to
- *     read data into (which should be at least @size bytes long).
+ * @buffer: (array length=size) (element-type guint8) (out caller-allocates):
+ *     a buffer to read data into (which should be at least @size bytes long).
  * @size: the number of bytes you want to read from the socket
  * @blocking: whether to do blocking or non-blocking I/O
  * @cancellable: (nullable): a %GCancellable or %NULL
@@ -41244,6 +41268,24 @@
 
 
 /**
+ * g_unix_mount_point_at:
+ * @mount_path: (type filename): path for a possible unix mount point.
+ * @time_read: (out) (optional): guint64 to contain a timestamp.
+ *
+ * Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it
+ * will be filled with a unix timestamp for checking if the mount points have
+ * changed since with g_unix_mount_points_changed_since().
+ *
+ * If more mount points have the same mount path, the last matching mount point
+ * is returned.
+ *
+ * Returns: (transfer full) (nullable): a #GUnixMountPoint, or %NULL if no match
+ * is found.
+ * Since: 2.66
+ */
+
+
+/**
  * g_unix_mount_point_compare:
  * @mount1: a #GUnixMount.
  * @mount2: a #GUnixMount.
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 3901e323..89d55033 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -2547,13 +2547,14 @@
  * Since #GUri only represents absolute URIs, all #GUris will have a
  * URI scheme, so g_uri_get_scheme() will always return a non-%NULL
  * answer. Likewise, by definition, all URIs have a path component, so
- * g_uri_get_path() will always return non-%NULL (though it may return
- * the empty string).
- *
- * If the URI string has an "authority" component (that is, if the
- * scheme is followed by "`://`" rather than just "`:`"), then the
- * #GUri will contain a hostname, and possibly a port and "userinfo".
- * Additionally, depending on how the #GUri was constructed/parsed,
+ * g_uri_get_path() will always return a non-%NULL string (which may be empty).
+ *
+ * If the URI string has an
+ * [‘authority’ component](https://tools.ietf.org/html/rfc3986#section-3) (that
+ * is, if the scheme is followed by `://` rather than just `:`), then the
+ * #GUri will contain a hostname, and possibly a port and ‘userinfo’.
+ * Additionally, depending on how the #GUri was constructed/parsed (for example,
+ * using the %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS flags),
  * the userinfo may be split out into a username, password, and
  * additional authorization-related parameters.
  *
@@ -2568,14 +2569,14 @@
  * For example, with the encoded flag:
  *
  * |[<!-- language="C" -->
- *   GUri *uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_ENCODED, &err);
+ *   g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_ENCODED, &err);
  *   g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue");
  * ]|
  *
  * While the default `%`-decoding behaviour would give:
  *
  * |[<!-- language="C" -->
- *   GUri *uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_NONE, &err);
+ *   g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_NONE, &err);
  *   g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http://host/path?param=value");
  * ]|
  *
@@ -2583,13 +2584,13 @@
  * with an error indicating the bad string location:
  *
  * |[<!-- language="C" -->
- *   GUri *uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fbad%3D%00alue", G_URI_FLAGS_NONE, &err);
- *   g_assert_error(err, G_URI_ERROR, G_URI_ERROR_BAD_QUERY);
+ *   g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fbad%3D%00alue", G_URI_FLAGS_NONE, &err);
+ *   g_assert_error (err, G_URI_ERROR, G_URI_ERROR_BAD_QUERY);
  * ]|
  *
  * You should pass %G_URI_FLAGS_ENCODED or %G_URI_FLAGS_ENCODED_QUERY if you
  * need to handle that case manually. In particular, if the query string
- * contains '=' characters that are '%'-encoded, you should let
+ * contains `=` characters that are `%`-encoded, you should let
  * g_uri_parse_params() do the decoding once of the query.
  *
  * #GUri is immutable once constructed, and can safely be accessed from
@@ -2600,6 +2601,23 @@
 
 
 /**
+ * GUriParamsIter:
+ *
+ * Many URI schemes include one or more attribute/value pairs as part of the URI
+ * value. For example `scheme://server/path?query=string&is=there` has two
+ * attributes – `query=string` and `is=there` – in its query part.
+ *
+ * A #GUriParamsIter structure represents an iterator that can be used to
+ * iterate over the attribute/value pairs of a URI query string. #GUriParamsIter
+ * structures are typically allocated on the stack and then initialized with
+ * g_uri_params_iter_init(). See the documentation for g_uri_params_iter_init()
+ * for a usage example.
+ *
+ * Since: 2.66
+ */
+
+
+/**
  * GVariant:
  *
  * #GVariant is an opaque data structure and can only be accessed
@@ -6076,12 +6094,50 @@
  * The #GUri type and related functions can be used to parse URIs into
  * their components, and build valid URIs from individual components.
  *
+ * Note that #GUri scope is to help manipulate URIs in various applications,
+ * following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular,
+ * it doesn't intend to cover web browser needs, and doesn't implement the
+ * [WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to
+ * help prevent
+ * [homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so
+ * #GUri is not suitable for formatting URIs for display to the user for making
+ * security-sensitive decisions.
+ *
+ * ## Relative and absolute URIs # {#relative-absolute-uris}
+ *
+ * As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4), the
+ * hierarchical nature of URIs means that they can either be ‘relative
+ * references’ (sometimes referred to as ‘relative URIs’) or ‘URIs’ (for
+ * clarity, ‘URIs’ are referred to in this documentation as
+ * ‘absolute URIs’ — although
+ * [in constrast to RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.3),
+ * fragment identifiers are always allowed).
+ *
+ * Relative references have one or more components of the URI missing. In
+ * particular, they have no scheme. Any other component, such as hostname,
+ * query, etc. may be missing, apart from a path, which has to be specified (but
+ * may be empty). The path may be relative, starting with `./` rather than `/`.
+ *
+ * For example, a valid relative reference is `./path?query`,
+ * `/?query#fragment` or `//example.com`.
+ *
+ * Absolute URIs have a scheme specified. Any other components of the URI which
+ * are missing are specified as explicitly unset in the URI, rather than being
+ * resolved relative to a base URI using g_uri_parse_relative().
+ *
+ * For example, a valid absolute URI is `file:///home/bob` or
+ * `https://search.com?query=string`.
+ *
+ * A #GUri instance is always an absolute URI. A string may be an absolute URI
+ * or a relative reference; see the documentation for individual functions as to
+ * what forms they accept.
+ *
  * ## Parsing URIs
  *
  * The most minimalist APIs for parsing URIs are g_uri_split() and
  * g_uri_split_with_user(). These split a URI into its component
  * parts, and return the parts; the difference between the two is that
- * g_uri_split() treats the "userinfo" component of the URI as a
+ * g_uri_split() treats the ‘userinfo’ component of the URI as a
  * single element, while g_uri_split_with_user() can (depending on the
  * #GUriFlags you pass) treat it as containing a username, password,
  * and authentication parameters. Alternatively, g_uri_split_network()
@@ -6106,20 +6162,23 @@
  * use g_uri_peek_scheme() on the URI string to check the scheme
  * first, and use that to decide what flags to parse it with.
  *
+ * For example, you might want to use %G_URI_PARAMS_WWW_FORM when parsing the
+ * params for a web URI, so compare the result of g_uri_peek_scheme() against
+ * `http` and `https`.
+ *
  * ## Building URIs
  *
  * g_uri_join() and g_uri_join_with_user() can be used to construct
- * valid URI strings from a set of component strings; they are the
+ * valid URI strings from a set of component strings. They are the
  * inverse of g_uri_split() and g_uri_split_with_user().
  *
  * Similarly, g_uri_build() and g_uri_build_with_user() can be used to
  * construct a #GUri from a set of component strings.
  *
  * As with the parsing functions, the building functions take a
- * #GUriFlags argument; in particular, it is important to keep in mind
- * whether the URI components you are using have `%`-encoded
- * characters in them or not, and pass the appropriate flags
- * accordingly.
+ * #GUriFlags argument. In particular, it is important to keep in mind
+ * whether the URI components you are using are already `%`-encoded. If so,
+ * you must pass the %G_URI_FLAGS_ENCODED flag.
  *
  * ## `file://` URIs
  *
@@ -6134,10 +6193,10 @@
  *
  * Note that there is no `g_uri_equal ()` function, because comparing
  * URIs usefully requires scheme-specific knowledge that #GUri does
- * not have. For example, "`http://example.com/`" and
- * "`http://EXAMPLE.COM:80`" have exactly the same meaning according
- * to the HTTP specification, and "`data:,foo`" and
- * "`data:;base64,Zm9v`" resolve to the same thing according to the
+ * not have. For example, `http://example.com/` and
+ * `http://EXAMPLE.COM:80` have exactly the same meaning according
+ * to the HTTP specification, and `data:,foo` and
+ * `data:;base64,Zm9v` resolve to the same thing according to the
  * `data:` URI specification.
  *
  * Since: 2.66
@@ -15136,7 +15195,7 @@
  * strftime() format language as specified by C99.  The \%D, \%U and \%W
  * conversions are not supported, nor is the 'E' modifier.  The GNU
  * extensions \%k, \%l, \%s and \%P are supported, however, as are the
- * '0', '_' and '-' modifiers.
+ * '0', '_' and '-' modifiers. The Python extension \%f is also supported.
  *
  * In contrast to strftime(), this function always produces a UTF-8
  * string, regardless of the current locale.  Note that the rendering of
@@ -15168,6 +15227,7 @@
  *   single digits are preceded by a blank
  * - \%m: the month as a decimal number (range 01 to 12)
  * - \%M: the minute as a decimal number (range 00 to 59)
+ * - \%f: the microsecond as a decimal number (range 000000 to 999999)
  * - \%p: either "AM" or "PM" according to the given time value, or the
  *   corresponding  strings for the current locale.  Noon is treated as
  *   "PM" and midnight as "AM". Use of this format specifier is discouraged, as
@@ -15245,6 +15305,8 @@
  * including the date, time and time zone, and return that as a UTF-8 encoded
  * string.
  *
+ * Since GLib 2.66, this will output to sub-second precision if needed.
+ *
  * Returns: (transfer full) (nullable): a newly allocated string formatted in
  *   ISO 8601 format or %NULL in the case that there was an error. The string
  *   should be freed with g_free().
@@ -18687,6 +18749,8 @@
  * Tests if @hostname is the string form of an IPv4 or IPv6 address.
  * (Eg, "192.168.0.1".)
  *
+ * Since 2.66, IPv6 addresses with a zone-id are accepted (RFC6874).
+ *
  * Returns: %TRUE if @hostname is an IP address
  * Since: 2.22
  */
@@ -35827,11 +35891,11 @@
 /**
  * g_uri_build:
  * @flags: flags describing how to build the #GUri
- * @scheme: the URI scheme
+ * @scheme: (not nullable): the URI scheme
  * @userinfo: (nullable): the userinfo component, or %NULL
  * @host: (nullable): the host component, or %NULL
- * @port: the port, or -1
- * @path: the path component
+ * @port: the port, or `-1`
+ * @path: (not nullable): the path component
  * @query: (nullable): the query component, or %NULL
  * @fragment: (nullable): the fragment, or %NULL
  *
@@ -35848,20 +35912,23 @@
 /**
  * g_uri_build_with_user:
  * @flags: flags describing how to build the #GUri
- * @scheme: the URI scheme
+ * @scheme: (not nullable): the URI scheme
  * @user: (nullable): the user component of the userinfo, or %NULL
  * @password: (nullable): the password component of the userinfo, or %NULL
  * @auth_params: (nullable): the auth params of the userinfo, or %NULL
  * @host: (nullable): the host component, or %NULL
- * @port: the port, or -1
- * @path: the path component
+ * @port: the port, or `-1`
+ * @path: (not nullable): the path component
  * @query: (nullable): the query component, or %NULL
  * @fragment: (nullable): the fragment, or %NULL
  *
- * Creates a new #GUri from the given components according to @flags.
+ * Creates a new #GUri from the given components according to @flags
+ * (%G_URI_FLAGS_HAS_PASSWORD is added unconditionally). The @flags must be
+ * coherent with the passed values, in particular use `%`-encoded values with
+ * %G_URI_FLAGS_ENCODED.
  *
- * In constrast to g_uri_build(), this allows specifying the components
- * of the "userinfo" field separately. Note that @user must be non-%NULL
+ * In contrast to g_uri_build(), this allows specifying the components
+ * of the ‘userinfo’ field separately. Note that @user must be non-%NULL
  * if either @password or @auth_params is non-%NULL.
  *
  * Returns: (transfer full): a new #GUri
@@ -35878,18 +35945,18 @@
  *
  * Escapes arbitrary data for use in a URI.
  *
- * Normally all characters that are not "unreserved" (i.e. ASCII
+ * Normally all characters that are not ‘unreserved’ (i.e. ASCII
  * alphanumerical characters plus dash, dot, underscore and tilde) are
  * escaped. But if you specify characters in @reserved_chars_allowed
- * they are not escaped. This is useful for the "reserved" characters
+ * they are not escaped. This is useful for the ‘reserved’ characters
  * in the URI specification, since those are allowed unescaped in some
  * portions of a URI.
  *
- * Though technically incorrect, this will also allow escaping "0"
- * bytes as "`%``00`".
+ * Though technically incorrect, this will also allow escaping nul
+ * bytes as `%``00`.
  *
- * Returns: an escaped version of @unescaped. The returned string
- * should be freed when no longer needed.
+ * Returns: (transfer full): an escaped version of @unescaped. The returned
+ *     string should be freed when no longer needed.
  * Since: 2.66
  */
 
@@ -35928,7 +35995,7 @@
  * Depending on the URI scheme, g_uri_parse_params() may be useful for
  * further parsing this information.
  *
- * Returns: @uri's authentication parameters.
+ * Returns: (nullable): @uri's authentication parameters.
  * Since: 2.66
  */
 
@@ -35951,7 +36018,7 @@
  * Gets @uri's fragment, which may contain `%`-encoding, depending on
  * the flags with which @uri was created.
  *
- * Returns: @uri's fragment.
+ * Returns: (nullable): @uri's fragment.
  * Since: 2.66
  */
 
@@ -35967,10 +36034,10 @@
  * If @uri contained an IPv6 address literal, this value will be just
  * that address, without the brackets around it that are necessary in
  * the string form of the URI. Note that in this case there may also
- * be a scope ID attached to the address. Eg, "`fe80::1234%``em1`" (or
- * "`fe80::1234%``25em1" if the string is still encoded).
+ * be a scope ID attached to the address. Eg, `fe80::1234%``em1` (or
+ * `fe80::1234%``25em1` if the string is still encoded).
  *
- * Returns: @uri's host.
+ * Returns: (not nullable): @uri's host.
  * Since: 2.66
  */
 
@@ -35983,7 +36050,7 @@
  * the flags with which @uri was created. (If @uri was not created
  * with %G_URI_FLAGS_HAS_PASSWORD then this will be %NULL.)
  *
- * Returns: @uri's password.
+ * Returns: (nullable): @uri's password.
  * Since: 2.66
  */
 
@@ -35995,7 +36062,7 @@
  * Gets @uri's path, which may contain `%`-encoding, depending on the
  * flags with which @uri was created.
  *
- * Returns: @uri's path.
+ * Returns: (not nullable): @uri's path.
  * Since: 2.66
  */
 
@@ -36006,7 +36073,7 @@
  *
  * Gets @uri's port.
  *
- * Returns: @uri's port, or -1 if no port was specified.
+ * Returns: @uri's port, or `-1` if no port was specified.
  * Since: 2.66
  */
 
@@ -36018,10 +36085,10 @@
  * Gets @uri's query, which may contain `%`-encoding, depending on the
  * flags with which @uri was created.
  *
- * For queries consisting of a series of "`name=value`" parameters,
- * g_uri_parse_params() may be useful.
+ * For queries consisting of a series of `name=value` parameters,
+ * #GUriParamsIter or g_uri_parse_params() may be useful.
  *
- * Returns: @uri's query.
+ * Returns: (nullable): @uri's query.
  * Since: 2.66
  */
 
@@ -36033,7 +36100,7 @@
  * Gets @uri's scheme. Note that this will always be all-lowercase,
  * regardless of the string or strings that @uri was created from.
  *
- * Returns: @uri's scheme.
+ * Returns: (not nullable): @uri's scheme.
  * Since: 2.66
  */
 
@@ -36042,12 +36109,12 @@
  * g_uri_get_user:
  * @uri: a #GUri
  *
- * Gets the "username" component of @uri's userinfo, which may contain
+ * Gets the ‘username’ component of @uri's userinfo, which may contain
  * `%`-encoding, depending on the flags with which @uri was created.
  * If @uri was not created with %G_URI_FLAGS_HAS_PASSWORD or
  * %G_URI_FLAGS_HAS_AUTH_PARAMS, this is the same as g_uri_get_userinfo().
  *
- * Returns: @uri's user.
+ * Returns: (nullable): @uri's user.
  * Since: 2.66
  */
 
@@ -36059,24 +36126,27 @@
  * Gets @uri's userinfo, which may contain `%`-encoding, depending on
  * the flags with which @uri was created.
  *
- * Returns: @uri's userinfo.
+ * Returns: (nullable): @uri's userinfo.
  * Since: 2.66
  */
 
 
 /**
  * g_uri_is_valid:
- * @uri_string: a string containing a relative or absolute URI
+ * @uri_string: a string containing an absolute URI
  * @flags: flags for parsing @uri_string
  * @error: #GError for error reporting, or %NULL to ignore.
  *
- * Parses @uri_string (which can be an absolute or relative URI)
- * according to @flags, to determine whether it is valid.
+ * Parses @uri_string according to @flags, to determine whether it is a valid
+ * [absolute URI][relative-absolute-uris], i.e. it does not need to be resolved
+ * relative to another URI using g_uri_parse_relative().
+ *
+ * If it’s not a valid URI, an error is returned explaining how it’s invalid.
  *
  * See g_uri_split(), and the definition of #GUriFlags, for more
  * information on the effect of @flags.
  *
- * Returns: %TRUE if @uri_string parsed successfully, %FALSE on error.
+ * Returns: %TRUE if @uri_string is a valid absolute URI, %FALSE on error.
  * Since: 2.66
  */
 
@@ -36084,22 +36154,30 @@
 /**
  * g_uri_join:
  * @flags: flags describing how to build the URI string
- * @scheme: the URI scheme
+ * @scheme: (nullable): the URI scheme, or %NULL
  * @userinfo: (nullable): the userinfo component, or %NULL
  * @host: (nullable): the host component, or %NULL
- * @port: the port, or -1
- * @path: the path component
+ * @port: the port, or `-1`
+ * @path: (not nullable): the path component
  * @query: (nullable): the query component, or %NULL
  * @fragment: (nullable): the fragment, or %NULL
  *
  * Joins the given components together according to @flags to create
- * a complete URI string. At least @scheme must be specified, and
- * @path may not be %NULL (though it may be "").
+ * an absolute URI string. @path may not be %NULL (though it may be the empty
+ * string).
+ *
+ * When @host is present, @path must either be empty or begin with a slash (`/`)
+ * character. When @host is not present, @path cannot begin with two slash
+ *    characters (`//`). See
+ * [RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3).
  *
  * See also g_uri_join_with_user(), which allows specifying the
- * components of the "userinfo" separately.
+ * components of the ‘userinfo’ separately.
+ *
+ * %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set
+ * in @flags.
  *
- * Returns: a URI string
+ * Returns: (transfer full): an absolute URI string
  * Since: 2.66
  */
 
@@ -36107,26 +36185,29 @@
 /**
  * g_uri_join_with_user:
  * @flags: flags describing how to build the URI string
- * @scheme: the URI scheme
+ * @scheme: (nullable): the URI scheme, or %NULL
  * @user: (nullable): the user component of the userinfo, or %NULL
  * @password: (nullable): the password component of the userinfo, or
  *   %NULL
  * @auth_params: (nullable): the auth params of the userinfo, or
  *   %NULL
  * @host: (nullable): the host component, or %NULL
- * @port: the port, or -1
- * @path: the path component
+ * @port: the port, or `-1`
+ * @path: (not nullable): the path component
  * @query: (nullable): the query component, or %NULL
  * @fragment: (nullable): the fragment, or %NULL
  *
  * Joins the given components together according to @flags to create
- * a complete URI string. At least @scheme must be specified, and
- * @path may not be %NULL (though it may be "").
+ * an absolute URI string. @path may not be %NULL (though it may be the empty
+ * string).
  *
- * In constrast to g_uri_join(), this allows specifying the components
- * of the "userinfo" separately.
+ * In contrast to g_uri_join(), this allows specifying the components
+ * of the ‘userinfo’ separately. It otherwise behaves the same.
  *
- * Returns: a URI string
+ * %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set
+ * in @flags.
+ *
+ * Returns: (transfer full): an absolute URI string
  * Since: 2.66
  */
 
@@ -36147,13 +36228,90 @@
 
 
 /**
+ * g_uri_params_iter_init:
+ * @iter: an uninitialized #GUriParamsIter
+ * @params: a `%`-encoded string containing `attribute=value`
+ *   parameters
+ * @length: the length of @params, or `-1` if it is nul-terminated
+ * @separators: the separator byte character set between parameters. (usually
+ *   `&`, but sometimes `;` or both `&;`). Note that this function works on
+ *   bytes not characters, so it can't be used to delimit UTF-8 strings for
+ *   anything but ASCII characters. You may pass an empty set, in which case
+ *   no splitting will occur.
+ * @flags: flags to modify the way the parameters are handled.
+ *
+ * Initializes an attribute/value pair iterator.
+ *
+ * The iterator keeps pointers to the @params and @separators arguments, those
+ * variables must thus outlive the iterator and not be modified during the
+ * iteration.
+ *
+ * If %G_URI_PARAMS_WWW_FORM is passed in @flags, `+` characters in the param
+ * string will be replaced with spaces in the output. For example, `foo=bar+baz`
+ * will give attribute `foo` with value `bar baz`. This is commonly used on the
+ * web (the `https` and `http` schemes only), but is deprecated in favour of
+ * the equivalent of encoding spaces as `%20`.
+ *
+ * Unlike with g_uri_parse_params(), %G_URI_PARAMS_CASE_INSENSITIVE has no
+ * effect if passed to @flags for g_uri_params_iter_init(). The caller is
+ * responsible for doing their own case-insensitive comparisons.
+ *
+ * |[<!-- language="C" -->
+ * GUriParamsIter iter;
+ * GError *error = NULL;
+ * gchar *unowned_attr, *unowned_value;
+ *
+ * g_uri_params_iter_init (&iter, "foo=bar&baz=bar&Foo=frob&baz=bar2", -1, "&", G_URI_PARAMS_NONE);
+ * while (g_uri_params_iter_next (&iter, &unowned_attr, &unowned_value, &error))
+ *   {
+ *     g_autofree gchar *attr = g_steal_pointer (&unowned_attr);
+ *     g_autofree gchar *value = g_steal_pointer (&unowned_value);
+ *     // do something with attr and value; this code will be called 4 times
+ *     // for the params string in this example: once with attr=foo and value=bar,
+ *     // then with baz/bar, then Foo/frob, then baz/bar2.
+ *   }
+ * if (error)
+ *   // handle parsing error
+ * ]|
+ *
+ * Since: 2.66
+ */
+
+
+/**
+ * g_uri_params_iter_next:
+ * @iter: an initialized #GUriParamsIter
+ * @attribute: (out) (nullable) (optional) (transfer full): on return, contains
+ *     the attribute, or %NULL.
+ * @value: (out) (nullable) (optional) (transfer full): on return, contains
+ *     the value, or %NULL.
+ * @error: #GError for error reporting, or %NULL to ignore.
+ *
+ * Advances @iter and retrieves the next attribute/value. %FALSE is returned if
+ * an error has occurred (in which case @error is set), or if the end of the
+ * iteration is reached (in which case @attribute and @value are set to %NULL
+ * and the iterator becomes invalid). If %TRUE is returned,
+ * g_uri_params_iter_next() may be called again to receive another
+ * attribute/value pair.
+ *
+ * Note that the same @attribute may be returned multiple times, since URIs
+ * allow repeated attributes.
+ *
+ * Returns: %FALSE if the end of the parameters has been reached or an error was
+ *     encountered. %TRUE otherwise.
+ * Since: 2.66
+ */
+
+
+/**
  * g_uri_parse:
  * @uri_string: a string representing an absolute URI
  * @flags: flags describing how to parse @uri_string
  * @error: #GError for error reporting, or %NULL to ignore.
  *
  * Parses @uri_string according to @flags. If the result is not a
- * valid absolute URI, it will be discarded, and an error returned.
+ * valid [absolute URI][relative-absolute-uris], it will be discarded, and an
+ * error returned.
  *
  * Returns: (transfer full): a new #GUri.
  * Since: 2.66
@@ -36162,11 +36320,11 @@
 
 /**
  * g_uri_parse_params:
- * @params: a `%`-encoded string containing "attribute=value"
+ * @params: a `%`-encoded string containing `attribute=value`
  *   parameters
- * @length: the length of @params, or -1 if it is NUL-terminated
+ * @length: the length of @params, or `-1` if it is nul-terminated
  * @separators: the separator byte character set between parameters. (usually
- *   "&", but sometimes ";" or both "&;"). Note that this function works on
+ *   `&`, but sometimes `;` or both `&;`). Note that this function works on
  *   bytes not characters, so it can't be used to delimit UTF-8 strings for
  *   anything but ASCII characters. You may pass an empty set, in which case
  *   no splitting will occur.
@@ -36174,35 +36332,48 @@
  * @error: #GError for error reporting, or %NULL to ignore.
  *
  * Many URI schemes include one or more attribute/value pairs as part of the URI
- * value. This method can be used to parse them into a hash table.
+ * value. This method can be used to parse them into a hash table. When an
+ * attribute has multiple occurrences, the last value is the final returned
+ * value. If you need to handle repeated attributes differently, use
+ * #GUriParamsIter.
  *
  * The @params string is assumed to still be `%`-encoded, but the returned
  * values will be fully decoded. (Thus it is possible that the returned values
- * may contain '=' or @separators, if the value was encoded in the input.)
- * Invalid `%`-encoding is treated as with the non-%G_URI_FLAGS_PARSE_STRICT
+ * may contain `=` or @separators, if the value was encoded in the input.)
+ * Invalid `%`-encoding is treated as with the %G_URI_FLAGS_PARSE_RELAXED
  * rules for g_uri_parse(). (However, if @params is the path or query string
- * from a #GUri that was parsed with %G_URI_FLAGS_PARSE_STRICT and
+ * from a #GUri that was parsed without %G_URI_FLAGS_PARSE_RELAXED and
  * %G_URI_FLAGS_ENCODED, then you already know that it does not contain any
  * invalid encoding.)
  *
- * Returns: (transfer full) (element-type utf8 utf8): a hash table of
- * attribute/value pairs. Both names and values will be fully-decoded. If
- * @params cannot be parsed (eg, it contains two @separators characters in a
- * row), then %NULL is returned.
+ * %G_URI_PARAMS_WWW_FORM is handled as documented for g_uri_params_iter_init().
+ *
+ * If %G_URI_PARAMS_CASE_INSENSITIVE is passed to @flags, attributes will be
+ * compared case-insensitively, so a params string `attr=123&Attr=456` will only
+ * return a single attribute–value pair, `Attr=456`. Case will be preserved in
+ * the returned attributes.
+ *
+ * If @params cannot be parsed (for example, it contains two @separators
+ * characters in a row), then @error is set and %NULL is returned.
+ *
+ * Returns: (transfer full) (element-type utf8 utf8): A hash table of
+ *     attribute/value pairs, with both names and values fully-decoded; or %NULL
+ *     on error.
  * Since: 2.66
  */
 
 
 /**
  * g_uri_parse_relative:
- * @base_uri: (nullable): a base URI
- * @uri_string: a string representing a relative or absolute URI
- * @flags: flags describing how to parse @uri_string
+ * @base_uri: (nullable) (transfer none): a base absolute URI
+ * @uri_ref: a string representing a relative or absolute URI
+ * @flags: flags describing how to parse @uri_ref
  * @error: #GError for error reporting, or %NULL to ignore.
  *
- * Parses @uri_string according to @flags and, if it is a relative
- * URI, resolves it relative to @base_uri. If the result is not a
- * valid absolute URI, it will be discarded, and an error returned.
+ * Parses @uri_ref according to @flags and, if it is a
+ * [relative URI][relative-absolute-uris], resolves it relative to @base_uri.
+ * If the result is not a valid absolute URI, it will be discarded, and an error
+ * returned.
  *
  * Returns: (transfer full): a new #GUri.
  * Since: 2.66
@@ -36213,14 +36384,16 @@
  * g_uri_parse_scheme:
  * @uri: a valid URI.
  *
- * Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as:
+ * Gets the scheme portion of a URI string.
+ * [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
+ * as:
  * |[
  * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
  * ]|
- * Common schemes include "file", "http", "svn+ssh", etc.
+ * Common schemes include `file`, `https`, `svn+ssh`, etc.
  *
- * Returns: The "scheme" component of the URI, or %NULL on error.
- * The returned string should be freed when no longer needed.
+ * Returns: (transfer full) (nullable): The ‘scheme’ component of the URI, or
+ *     %NULL on error. The returned string should be freed when no longer needed.
  * Since: 2.16
  */
 
@@ -36229,15 +36402,20 @@
  * g_uri_peek_scheme:
  * @uri: a valid URI.
  *
- * Gets the scheme portion of a URI string. RFC 3986 decodes the scheme as:
+ * Gets the scheme portion of a URI string.
+ * [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
+ * as:
  * |[
  * URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
  * ]|
- * Common schemes include "file", "http", "svn+ssh", etc.
+ * Common schemes include `file`, `https`, `svn+ssh`, etc.
+ *
+ * Unlike g_uri_parse_scheme(), the returned scheme is normalized to
+ * all-lowercase and does not need to be freed.
  *
- * Returns: The "scheme" component of the URI, or %NULL on error. The
- * returned string is normalized to all-lowercase, and interned via
- * g_intern_string(), so it does not need to be freed.
+ * Returns: (transfer none) (nullable): The ‘scheme’ component of the URI, or
+ *     %NULL on error. The returned string is normalized to all-lowercase, and
+ *     interned via g_intern_string(), so it does not need to be freed.
  * Since: 2.66
  */
 
@@ -36256,35 +36434,36 @@
 /**
  * g_uri_resolve_relative:
  * @base_uri_string: (nullable): a string representing a base URI
- * @uri_string: a string representing a relative or absolute URI
- * @flags: flags describing how to parse @uri_string
+ * @uri_ref: a string representing a relative or absolute URI
+ * @flags: flags describing how to parse @uri_ref
  * @error: #GError for error reporting, or %NULL to ignore.
  *
- * Parses @uri_string according to @flags and, if it is a relative
- * URI, resolves it relative to @base_uri_string. If the result is not
- * a valid absolute URI, it will be discarded, and an error returned.
+ * Parses @uri_ref according to @flags and, if it is a
+ * [relative URI][relative-absolute-uris], resolves it relative to
+ * @base_uri_string. If the result is not a valid absolute URI, it will be
+ * discarded, and an error returned.
  *
- * (If @base_uri_string is %NULL, this just returns @uri_string, or
- * %NULL if @uri_string is invalid or not absolute.)
+ * (If @base_uri_string is %NULL, this just returns @uri_ref, or
+ * %NULL if @uri_ref is invalid or not absolute.)
  *
- * Returns: the resolved URI string.
+ * Returns: (transfer full): the resolved URI string.
  * Since: 2.66
  */
 
 
 /**
  * g_uri_split:
- * @uri_string: a string containing a relative or absolute URI
- * @flags: flags for parsing @uri_string
+ * @uri_ref: a string containing a relative or absolute URI
+ * @flags: flags for parsing @uri_ref
  * @scheme: (out) (nullable) (optional) (transfer full): on return, contains
  *    the scheme (converted to lowercase), or %NULL
  * @userinfo: (out) (nullable) (optional) (transfer full): on return, contains
  *    the userinfo, or %NULL
  * @host: (out) (nullable) (optional) (transfer full): on return, contains the
  *    host, or %NULL
- * @port: (out) (nullable) (optional) (transfer full): on return, contains the
- *    port, or -1
- * @path: (out) (nullable) (optional) (transfer full): on return, contains the
+ * @port: (out) (optional) (transfer full): on return, contains the
+ *    port, or `-1`
+ * @path: (out) (not nullable) (optional) (transfer full): on return, contains the
  *    path
  * @query: (out) (nullable) (optional) (transfer full): on return, contains the
  *    query, or %NULL
@@ -36292,14 +36471,14 @@
  *    the fragment, or %NULL
  * @error: #GError for error reporting, or %NULL to ignore.
  *
- * Parses @uri_string (which can be an absolute or relative URI)
- * according to @flags, and returns the pieces. Any component that
- * doesn't appear in @uri_string will be returned as %NULL (but note
- * that all URIs always have a path component, though it may be the
- * empty string).
+ * Parses @uri_ref (which can be an
+ * [absolute or relative URI][relative-absolute-uris]) according to @flags, and
+ * returns the pieces. Any component that doesn't appear in @uri_ref will be
+ * returned as %NULL (but note that all URIs always have a path component,
+ * though it may be the empty string).
  *
  * If @flags contains %G_URI_FLAGS_ENCODED, then `%`-encoded characters in
- * @uri_string will remain encoded in the output strings. (If not,
+ * @uri_ref will remain encoded in the output strings. (If not,
  * then all such characters will be decoded.) Note that decoding will
  * only work if the URI components are ASCII or UTF-8, so you will
  * need to use %G_URI_FLAGS_ENCODED if they are not.
@@ -36309,7 +36488,7 @@
  * since it always returns only the full userinfo; use
  * g_uri_split_with_user() if you want it split up.
  *
- * Returns: (skip): %TRUE if @uri_string parsed successfully, %FALSE
+ * Returns: (skip): %TRUE if @uri_ref parsed successfully, %FALSE
  *   on error.
  * Since: 2.66
  */
@@ -36317,18 +36496,18 @@
 
 /**
  * g_uri_split_network:
- * @uri_string: a string containing a relative or absolute URI
+ * @uri_string: a string containing an absolute URI
  * @flags: flags for parsing @uri_string
  * @scheme: (out) (nullable) (optional) (transfer full): on return, contains
  *    the scheme (converted to lowercase), or %NULL
  * @host: (out) (nullable) (optional) (transfer full): on return, contains the
  *    host, or %NULL
- * @port: (out) (nullable) (optional) (transfer full): on return, contains the
- *    port, or -1
+ * @port: (out) (optional) (transfer full): on return, contains the
+ *    port, or `-1`
  * @error: #GError for error reporting, or %NULL to ignore.
  *
- * Parses @uri_string (which must be an absolute URI) according to
- * @flags, and returns the pieces relevant to connecting to a host.
+ * Parses @uri_string (which must be an [absolute URI][relative-absolute-uris])
+ * according to @flags, and returns the pieces relevant to connecting to a host.
  * See the documentation for g_uri_split() for more details; this is
  * mostly a wrapper around that function with simpler arguments.
  * However, it will return an error if @uri_string is a relative URI,
@@ -36342,8 +36521,8 @@
 
 /**
  * g_uri_split_with_user:
- * @uri_string: a string containing a relative or absolute URI
- * @flags: flags for parsing @uri_string
+ * @uri_ref: a string containing a relative or absolute URI
+ * @flags: flags for parsing @uri_ref
  * @scheme: (out) (nullable) (optional) (transfer full): on return, contains
  *    the scheme (converted to lowercase), or %NULL
  * @user: (out) (nullable) (optional) (transfer full): on return, contains
@@ -36354,9 +36533,9 @@
  *    the auth_params, or %NULL
  * @host: (out) (nullable) (optional) (transfer full): on return, contains the
  *    host, or %NULL
- * @port: (out) (nullable) (optional) (transfer full): on return, contains the
- *    port, or -1
- * @path: (out) (nullable) (optional) (transfer full): on return, contains the
+ * @port: (out) (optional) (transfer full): on return, contains the
+ *    port, or `-1`
+ * @path: (out) (not nullable) (optional) (transfer full): on return, contains the
  *    path
  * @query: (out) (nullable) (optional) (transfer full): on return, contains the
  *    query, or %NULL
@@ -36364,11 +36543,11 @@
  *    the fragment, or %NULL
  * @error: #GError for error reporting, or %NULL to ignore.
  *
- * Parses @uri_string (which can be an absolute or relative URI)
- * according to @flags, and returns the pieces. Any component that
- * doesn't appear in @uri_string will be returned as %NULL (but note
- * that all URIs always have a path component, though it may be the
- * empty string).
+ * Parses @uri_ref (which can be an
+ * [absolute or relative URI][relative-absolute-uris]) according to @flags, and
+ * returns the pieces. Any component that doesn't appear in @uri_ref will be
+ * returned as %NULL (but note that all URIs always have a path component,
+ * though it may be the empty string).
  *
  * See g_uri_split(), and the definition of #GUriFlags, for more
  * information on the effect of @flags. Note that @password will only
@@ -36376,7 +36555,7 @@
  * @auth_params will only be parsed out if @flags contains
  * %G_URI_FLAGS_HAS_AUTH_PARAMS.
  *
- * Returns: (skip): %TRUE if @uri_string parsed successfully, %FALSE
+ * Returns: (skip): %TRUE if @uri_ref parsed successfully, %FALSE
  *   on error.
  * Since: 2.66
  */
@@ -36395,8 +36574,12 @@
  * a string which is at least semantically equivalent to the source
  * URI (according to RFC 3986).
  *
- * Returns: a string representing @uri, which the caller must
- * free.
+ * If @uri might contain sensitive details, such as authentication parameters,
+ * or private data in its query string, and the returned string is going to be
+ * logged, then consider using g_uri_to_string_partial() to redact parts.
+ *
+ * Returns: (transfer full): a string representing @uri, which the caller
+ *     must free.
  * Since: 2.66
  */
 
@@ -36409,8 +36592,8 @@
  * Returns a string representing @uri, subject to the options in
  * @flags. See g_uri_to_string() and #GUriHideFlags for more details.
  *
- * Returns: a string representing @uri, which the caller must
- * free.
+ * Returns: (transfer full): a string representing @uri, which the caller
+ *     must free.
  * Since: 2.66
  */
 
@@ -36418,8 +36601,8 @@
 /**
  * g_uri_unescape_bytes:
  * @escaped_string: A URI-escaped string
- * @length: the length of @escaped_string to escape, or -1 if it
- *   is NUL-terminated.
+ * @length: the length (in bytes) of @escaped_string to escape, or `-1` if it
+ *   is nul-terminated.
  * @illegal_characters: (nullable): a string of illegal characters
  *   not to be allowed, or %NULL.
  * @error: #GError for error reporting, or %NULL to ignore.
@@ -36427,17 +36610,17 @@
  * Unescapes a segment of an escaped string as binary data.
  *
  * Note that in contrast to g_uri_unescape_string(), this does allow
- * `NUL` bytes to appear in the output.
+ * nul bytes to appear in the output.
  *
- * If any of the characters in @illegal_characters or the NUL
- * character appears as an escaped character in @escaped_string, then
- * that is an error and %NULL will be returned. This is useful if you
- * want to avoid for instance having a slash being expanded in an
- * escaped path element, which might confuse pathname handling.
+ * If any of the characters in @illegal_characters appears as an escaped
+ * character in @escaped_string, then that is an error and %NULL will be
+ * returned. This is useful if you want to avoid for instance having a slash
+ * being expanded in an escaped path element, which might confuse pathname
+ * handling.
  *
  * Returns: (transfer full): an unescaped version of @escaped_string or %NULL on
- * error (if decoding failed, using %G_URI_ERROR_MISC error code). The returned
- * #GBytes should be unreffed when no longer needed.
+ *     error (if decoding failed, using %G_URI_ERROR_FAILED error code). The
+ *     returned #GBytes should be unreffed when no longer needed.
  * Since: 2.66
  */