@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/glib/uri.js

@@ -1,5 +1,168 @@
 import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
+/**
+ * The `GUri` type and related functions can be used to parse URIs into
+ * their components, and build valid URIs from individual components.
+ *
+ * Since `GUri` only represents absolute URIs, all `GUri`s will have a
+ * URI scheme, so [method@GLib.Uri.get_scheme] will always return a non-`NULL`
+ * answer. Likewise, by definition, all URIs have a path component, so
+ * [method@GLib.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.
+ *
+ * Normally, the components of a `GUri` will have all `%`-encoded
+ * characters decoded. However, if you construct/parse a `GUri` with
+ * `G_URI_FLAGS_ENCODED`, then the `%`-encoding will be preserved instead in
+ * the userinfo, path, and query fields (and in the host field if also
+ * created with `G_URI_FLAGS_NON_DNS`). In particular, this is necessary if
+ * the URI may contain binary data or non-UTF-8 text, or if decoding
+ * the components might change the interpretation of the URI.
+ *
+ * For example, with the encoded flag:
+ *
+ * ```c
+ * 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:
+ *
+ * ```c
+ * 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");
+ * ```
+ *
+ * During decoding, if an invalid UTF-8 string is encountered, parsing will fail
+ * with an error indicating the bad string location:
+ *
+ * ```c
+ * 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
+ * [func@GLib.Uri.parse_params] do the decoding once of the query.
+ *
+ * `GUri` is immutable once constructed, and can safely be accessed from
+ * multiple threads. Its reference counting is atomic.
+ *
+ * Note that the scope of `GUri` 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
+ *
+ * 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 contrast 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 [method@GLib.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 [func@GLib.Uri.split] and
+ * [func@GLib.Uri.split_with_user]. These split a URI into its component
+ * parts, and return the parts; the difference between the two is that
+ * [func@GLib.Uri.split] treats the ‘userinfo’ component of the URI as a
+ * single element, while [func@GLib.Uri.split_with_user] can (depending on the
+ * [flags@GLib.UriFlags] you pass) treat it as containing a username, password,
+ * and authentication parameters. Alternatively, [func@GLib.Uri.split_network]
+ * can be used when you are only interested in the components that are
+ * needed to initiate a network connection to the service (scheme,
+ * host, and port).
+ *
+ * [func@GLib.Uri.parse] is similar to [func@GLib.Uri.split], but instead of
+ * returning individual strings, it returns a `GUri` structure (and it requires
+ * that the URI be an absolute URI).
+ *
+ * [func@GLib.Uri.resolve_relative] and [method@GLib.Uri.parse_relative] allow
+ * you to resolve a relative URI relative to a base URI.
+ * [func@GLib.Uri.resolve_relative] takes two strings and returns a string,
+ * and [method@GLib.Uri.parse_relative] takes a `GUri` and a string and returns a
+ * `GUri`.
+ *
+ * All of the parsing functions take a [flags@GLib.UriFlags] argument describing
+ * exactly how to parse the URI; see the documentation for that type
+ * for more details on the specific flags that you can pass. If you
+ * need to choose different flags based on the type of URI, you can
+ * use [func@GLib.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 [func@GLib.Uri.peek_scheme]
+ * against `http` and `https`.
+ *
+ * ## Building URIs
+ *
+ * [func@GLib.Uri.join] and [func@GLib.Uri.join_with_user] can be used to construct
+ * valid URI strings from a set of component strings. They are the
+ * inverse of [func@GLib.Uri.split] and [func@GLib.Uri.split_with_user].
+ *
+ * Similarly, [func@GLib.Uri.build] and [func@GLib.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
+ * [flags@GLib.UriFlags] 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
+ *
+ * Note that Windows and Unix both define special rules for parsing
+ * `file://` URIs (involving non-UTF-8 character sets on Unix, and the
+ * interpretation of path separators on Windows). `GUri` does not
+ * implement these rules. Use [func@GLib.filename_from_uri] and
+ * [func@GLib.filename_to_uri] if you want to properly convert between
+ * `file://` URIs and local filenames.
+ *
+ * ## URI Equality
+ *
+ * Note that there is no `g_uri_equal ()` function, because comparing
+ * URIs usefully requires scheme-specific knowledge that `GUri` does
+ * not have. `GUri` can help with normalization if you use the various
+ * encoded [flags@GLib.UriFlags] as well as `G_URI_FLAGS_SCHEME_NORMALIZE`
+ * however it is not comprehensive.
+ * For example, `data:,foo` and `data:;base64,Zm9v` resolve to the same
+ * thing according to the `data:` URI specification which GLib does not
+ * handle.
+ */
 export class Uri {
     ptr;
     constructor() {
@@ -8,6 +171,20 @@ export class Uri {
     createPtr(_init) {
         return null;
     }
+    /**
+     * Creates a new #GUri from the given components according to @flags.
+     *
+     * See also g_uri_build_with_user(), which allows specifying the
+     * components of the "userinfo" separately.
+     * @param flags - flags describing how to build the #GUri
+     * @param scheme - the URI scheme
+     * @param userinfo - the userinfo component, or %NULL
+     * @param host - the host component, or %NULL
+     * @param port - the port, or `-1`
+     * @param path - the path component
+     * @param query - the query component, or %NULL
+     * @param fragment - the fragment, or %NULL
+     */
     static build(flags, scheme, port, path, userinfo, host, query, fragment) {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_build", [
             {
@@ -54,6 +231,25 @@ export class Uri {
         });
         return getObject(ptr, Uri);
     }
+    /**
+     * 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 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.
+     * @param flags - flags describing how to build the #GUri
+     * @param scheme - the URI scheme
+     * @param user - the user component of the userinfo, or %NULL
+     * @param password - the password component of the userinfo, or %NULL
+     * @param authParams - the auth params of the userinfo, or %NULL
+     * @param host - the host component, or %NULL
+     * @param port - the port, or `-1`
+     * @param path - the path component
+     * @param query - the query component, or %NULL
+     * @param fragment - the fragment, or %NULL
+     */
     static buildWithUser(flags, scheme, port, path, user, password, authParams, host, query, fragment) {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_build_with_user", [
             {
@@ -113,6 +309,21 @@ export class Uri {
     static errorQuark() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_error_quark", [], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * Escapes arbitrary data for use in a URI.
+     *
+     * 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
+     * in the URI specification, since those are allowed unescaped in some
+     * portions of a URI.
+     *
+     * Though technically incorrect, this will also allow escaping nul
+     * bytes as `%``00`.
+     * @param unescaped - the unescaped input data.
+     * @param length - the length of @unescaped
+     * @param reservedCharsAllowed - a string of reserved
+     */
     static escapeBytes(unescaped, length, reservedCharsAllowed) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_escape_bytes", [
             {
@@ -133,6 +344,18 @@ export class Uri {
             },
         ], { type: "string" });
     }
+    /**
+     * Escapes a string for use in a URI.
+     *
+     * 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
+     * in the URI specification, since those are allowed unescaped in some
+     * portions of a URI.
+     * @param unescaped - the unescaped input string.
+     * @param reservedCharsAllowed - a string of reserved
+     * @param allowUtf8 - %TRUE if the result can include UTF-8 characters.
+     */
     static escapeString(unescaped, allowUtf8, reservedCharsAllowed) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_escape_string", [
             {
@@ -150,6 +373,18 @@ export class Uri {
             },
         ], { type: "string" });
     }
+    /**
+     * Parses `uri_string` according to @flags, to determine whether it is a valid
+     * [absolute URI](#relative-and-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.
+     * @param uriString - a string containing an absolute URI
+     * @param flags - flags for parsing @uri_string
+     */
     static isValid(uriString, flags) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_is_valid", [
@@ -178,6 +413,30 @@ export class Uri {
         }
         return result;
     }
+    /**
+     * Joins the given components together according to `flags` to create
+     * 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.
+     *
+     * %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set
+     * in @flags.
+     * @param flags - flags describing how to build the URI string
+     * @param scheme - the URI scheme, or %NULL
+     * @param userinfo - the userinfo component, or %NULL
+     * @param host - the host component, or %NULL
+     * @param port - the port, or `-1`
+     * @param path - the path component
+     * @param query - the query component, or %NULL
+     * @param fragment - the fragment, or %NULL
+     */
     static join(flags, port, path, scheme, userinfo, host, query, fragment) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_join", [
             {
@@ -219,6 +478,27 @@ export class Uri {
             },
         ], { type: "string" });
     }
+    /**
+     * Joins the given components together according to `flags` to create
+     * an absolute URI string. `path` may not be %NULL (though it may be the empty
+     * string).
+     *
+     * In contrast to g_uri_join(), this allows specifying the components
+     * of the ‘userinfo’ separately. It otherwise behaves the same.
+     *
+     * %G_URI_FLAGS_HAS_PASSWORD and %G_URI_FLAGS_HAS_AUTH_PARAMS are ignored if set
+     * in @flags.
+     * @param flags - flags describing how to build the URI string
+     * @param scheme - the URI scheme, or %NULL
+     * @param user - the user component of the userinfo, or %NULL
+     * @param password - the password component of the userinfo, or
+     * @param authParams - the auth params of the userinfo, or
+     * @param host - the host component, or %NULL
+     * @param port - the port, or `-1`
+     * @param path - the path component
+     * @param query - the query component, or %NULL
+     * @param fragment - the fragment, or %NULL
+     */
     static joinWithUser(flags, port, path, scheme, user, password, authParams, host, query, fragment) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_join_with_user", [
             {
@@ -270,6 +550,12 @@ export class Uri {
             },
         ], { type: "string" });
     }
+    /**
+     * Splits an URI list conforming to the text/uri-list
+     * mime type defined in RFC 2483 into individual URIs,
+     * discarding any comments. The URIs are not validated.
+     * @param uriList - an URI list
+     */
     static listExtractUris(uriList) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_list_extract_uris", [
             {
@@ -278,6 +564,13 @@ export class Uri {
             },
         ], { type: "array", itemType: { type: "string" } });
     }
+    /**
+     * Parses `uri_string` according to @flags. If the result is not a
+     * valid [absolute URI](#relative-and-absolute-uris), it will be discarded, and an
+     * error returned.
+     * @param uriString - a string representing an absolute URI
+     * @param flags - flags describing how to parse @uri_string
+     */
     static parse(uriString, flags) {
         const error = { value: null };
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_parse", [
@@ -311,6 +604,35 @@ export class Uri {
         }
         return getObject(ptr, Uri);
     }
+    /**
+     * 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. 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 %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 without %G_URI_FLAGS_PARSE_RELAXED and
+     * %G_URI_FLAGS_ENCODED, then you already know that it does not contain any
+     * invalid encoding.)
+     *
+     * %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.
+     * @param params - a `%`-encoded string containing `attribute=value`
+     * @param length - the length of @params, or `-1` if it is nul-terminated
+     * @param separators - the separator byte character set between parameters. (usually
+     * @param flags - flags to modify the way the parameters are handled.
+     */
     static parseParams(params, length, separators, flags) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_parse_params", [
@@ -352,6 +674,16 @@ export class Uri {
         }
         return result;
     }
+    /**
+     * 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`, `https`, `svn+ssh`, etc.
+     * @param uri - a valid URI.
+     */
     static parseScheme(uri) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_parse_scheme", [
             {
@@ -360,6 +692,19 @@ export class Uri {
             },
         ], { type: "string" });
     }
+    /**
+     * 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`, `https`, `svn+ssh`, etc.
+     *
+     * Unlike g_uri_parse_scheme(), the returned scheme is normalized to
+     * all-lowercase and does not need to be freed.
+     * @param uri - a valid URI.
+     */
     static peekScheme(uri) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_peek_scheme", [
             {
@@ -368,6 +713,18 @@ export class Uri {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Parses `uri_ref` according to `flags` and, if it is a
+     * [relative URI](#relative-and-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_ref, or
+     * %NULL if `uri_ref` is invalid or not absolute.)
+     * @param baseUriString - a string representing a base URI
+     * @param uriRef - a string representing a relative or absolute URI
+     * @param flags - flags describing how to parse @uri_ref
+     */
     static resolveRelative(uriRef, flags, baseUriString) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_resolve_relative", [
@@ -401,6 +758,33 @@ export class Uri {
         }
         return result;
     }
+    /**
+     * Parses `uri_ref` (which can be an
+     * [absolute or relative URI](#relative-and-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_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.
+     *
+     * Note that the %G_URI_FLAGS_HAS_PASSWORD and
+     * %G_URI_FLAGS_HAS_AUTH_PARAMS `flags` are ignored by g_uri_split(),
+     * since it always returns only the full userinfo; use
+     * g_uri_split_with_user() if you want it split up.
+     * @param uriRef - a string containing a relative or absolute URI
+     * @param flags - flags for parsing @uri_ref
+     * @param scheme - on return, contains
+     * @param userinfo - on return, contains
+     * @param host - on return, contains the
+     * @param port - on return, contains the
+     * @param path - on return, contains the
+     * @param query - on return, contains the
+     * @param fragment - on return, contains
+     */
     static split(uriRef, flags, scheme, userinfo, host, port, path, query, fragment) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_split", [
@@ -467,6 +851,19 @@ export class Uri {
         }
         return result;
     }
+    /**
+     * Parses `uri_string` (which must be an [absolute URI](#relative-and-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,
+     * or does not contain a hostname component.
+     * @param uriString - a string containing an absolute URI
+     * @param flags - flags for parsing @uri_string
+     * @param scheme - on return, contains
+     * @param host - on return, contains the
+     * @param port - on return, contains the
+     */
     static splitNetwork(uriString, flags, scheme, host, port) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_split_network", [
@@ -513,6 +910,30 @@ export class Uri {
         }
         return result;
     }
+    /**
+     * Parses `uri_ref` (which can be an
+     * [absolute or relative URI](#relative-and-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
+     * be parsed out if `flags` contains %G_URI_FLAGS_HAS_PASSWORD, and
+     * `auth_params` will only be parsed out if `flags` contains
+     * %G_URI_FLAGS_HAS_AUTH_PARAMS.
+     * @param uriRef - a string containing a relative or absolute URI
+     * @param flags - flags for parsing @uri_ref
+     * @param scheme - on return, contains
+     * @param user - on return, contains
+     * @param password - on return, contains
+     * @param authParams - on return, contains
+     * @param host - on return, contains the
+     * @param port - on return, contains the
+     * @param path - on return, contains the
+     * @param query - on return, contains the
+     * @param fragment - on return, contains
+     */
     static splitWithUser(uriRef, flags, scheme, user, password, authParams, host, port, path, query, fragment) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_split_with_user", [
@@ -589,6 +1010,21 @@ export class Uri {
         }
         return result;
     }
+    /**
+     * 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.
+     *
+     * 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.
+     * @param escapedString - A URI-escaped string
+     * @param length - the length (in bytes) of `escaped_string` to escape, or `-1` if it
+     * @param illegalCharacters - a string of illegal characters
+     */
     static unescapeBytes(escapedString, length, illegalCharacters) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_unescape_bytes", [
@@ -627,6 +1063,21 @@ export class Uri {
         }
         return result;
     }
+    /**
+     * Unescapes a segment of an escaped string.
+     *
+     * 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.
+     *
+     * Note: `NUL` byte is not accepted in the output, in contrast to
+     * g_uri_unescape_bytes().
+     * @param escapedString - A string, may be %NULL
+     * @param escapedStringEnd - Pointer to end of @escaped_string,
+     * @param illegalCharacters - An optional string of illegal
+     */
     static unescapeSegment(escapedString, escapedStringEnd, illegalCharacters) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_unescape_segment", [
             {
@@ -646,6 +1097,17 @@ export class Uri {
             },
         ], { type: "string" });
     }
+    /**
+     * Unescapes a whole escaped string.
+     *
+     * 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.
+     * @param escapedString - an escaped string to be unescaped.
+     * @param illegalCharacters - a string of illegal characters
+     */
     static unescapeString(escapedString, illegalCharacters) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_unescape_string", [
             {
@@ -659,6 +1121,15 @@ export class Uri {
             },
         ], { type: "string" });
     }
+    /**
+     * Gets @uri's authentication parameters, which may contain
+     * `%`-encoding, depending on the flags with which `uri` was created.
+     * (If `uri` was not created with %G_URI_FLAGS_HAS_AUTH_PARAMS then this will
+     * be %NULL.)
+     *
+     * Depending on the URI scheme, g_uri_parse_params() may be useful for
+     * further parsing this information.
+     */
     getAuthParams() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_get_auth_params", [
             {
@@ -667,6 +1138,9 @@ export class Uri {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets @uri's flags set upon construction.
+     */
     getFlags() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_get_flags", [
             {
@@ -675,6 +1149,10 @@ export class Uri {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets @uri's fragment, which may contain `%`-encoding, depending on
+     * the flags with which `uri` was created.
+     */
     getFragment() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_get_fragment", [
             {
@@ -683,6 +1161,17 @@ export class Uri {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets @uri's host. This will never have `%`-encoded characters,
+     * unless it is non-UTF-8 (which can only be the case if `uri` was
+     * created with %G_URI_FLAGS_NON_DNS).
+     *
+     * 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).
+     */
     getHost() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_get_host", [
             {
@@ -691,6 +1180,11 @@ export class Uri {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets @uri's password, which may contain `%`-encoding, depending on
+     * the flags with which `uri` was created. (If `uri` was not created
+     * with %G_URI_FLAGS_HAS_PASSWORD then this will be %NULL.)
+     */
     getPassword() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_get_password", [
             {
@@ -699,6 +1193,10 @@ export class Uri {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets @uri's path, which may contain `%`-encoding, depending on the
+     * flags with which `uri` was created.
+     */
     getPath() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_get_path", [
             {
@@ -707,6 +1205,9 @@ export class Uri {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets @uri's port.
+     */
     getPort() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_get_port", [
             {
@@ -715,6 +1216,13 @@ export class Uri {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * 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,
+     * #GUriParamsIter or g_uri_parse_params() may be useful.
+     */
     getQuery() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_get_query", [
             {
@@ -723,6 +1231,10 @@ export class Uri {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets @uri's scheme. Note that this will always be all-lowercase,
+     * regardless of the string or strings that `uri` was created from.
+     */
     getScheme() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_get_scheme", [
             {
@@ -731,6 +1243,12 @@ export class Uri {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * 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().
+     */
     getUser() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_get_user", [
             {
@@ -739,6 +1257,10 @@ export class Uri {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Gets @uri's userinfo, which may contain `%`-encoding, depending on
+     * the flags with which `uri` was created.
+     */
     getUserinfo() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_get_userinfo", [
             {
@@ -747,6 +1269,14 @@ export class Uri {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Parses `uri_ref` according to `flags` and, if it is a
+     * [relative URI](#relative-and-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.
+     * @param uriRef - a string representing a relative or absolute URI
+     * @param flags - flags describing how to parse @uri_ref
+     */
     parseRelative(uriRef, flags) {
         const error = { value: null };
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_parse_relative", [
@@ -784,6 +1314,20 @@ export class Uri {
         }
         return getObject(ptr, Uri);
     }
+    /**
+     * Returns a string representing @uri.
+     *
+     * This is not guaranteed to return a string which is identical to the
+     * string that `uri` was parsed from. However, if the source URI was
+     * syntactically correct (according to RFC 3986), and it was parsed
+     * with %G_URI_FLAGS_ENCODED, then g_uri_to_string() is guaranteed to return
+     * a string which is at least semantically equivalent to the source
+     * URI (according to RFC 3986).
+     *
+     * 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.
+     */
     toString() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_to_string", [
             {
@@ -792,6 +1336,11 @@ export class Uri {
             },
         ], { type: "string" });
     }
+    /**
+     * Returns a string representing @uri, subject to the options in
+     * @flags. See g_uri_to_string() and #GUriHideFlags for more details.
+     * @param flags - flags describing what parts of `uri` to hide
+     */
     toStringPartial(flags) {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_uri_to_string_partial", [
             {