@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/glib/variant.d.ts

@@ -3,86 +3,1218 @@ import { VariantClass } from "./enums.js";
 import { Bytes } from "./bytes.js";
 import { GError } from "./error.js";
 import { VariantType } from "./variant-type.js";
+/**
+ * `GVariant` is a variant datatype; it can contain one or more values
+ * along with information about the type of the values.
+ *
+ * A `GVariant` may contain simple types, like an integer, or a boolean value;
+ * or complex types, like an array of two strings, or a dictionary of key
+ * value pairs. A `GVariant` is also immutable: once it’s been created neither
+ * its type nor its content can be modified further.
+ *
+ * `GVariant` is useful whenever data needs to be serialized, for example when
+ * sending method parameters in D-Bus, or when saving settings using
+ * `GSettings`.
+ *
+ * When creating a new `GVariant`, you pass the data you want to store in it
+ * along with a string representing the type of data you wish to pass to it.
+ *
+ * For instance, if you want to create a `GVariant` holding an integer value you
+ * can use:
+ *
+ * ```c
+ * GVariant *v = g_variant_new ("u", 40);
+ * ```
+ *
+ * The string `u` in the first argument tells `GVariant` that the data passed to
+ * the constructor (`40`) is going to be an unsigned integer.
+ *
+ * More advanced examples of `GVariant` in use can be found in documentation for
+ * `GVariant` format strings.
+ *
+ * The range of possible values is determined by the type.
+ *
+ * The type system used by `GVariant` is [type@GLib.VariantType].
+ *
+ * `GVariant` instances always have a type and a value (which are given
+ * at construction time).  The type and value of a `GVariant` instance
+ * can never change other than by the `GVariant` itself being
+ * destroyed.  A `GVariant` cannot contain a pointer.
+ *
+ * `GVariant` is reference counted using [method@GLib.Variant.ref] and
+ * [method@GLib.Variant.unref].  `GVariant` also has floating reference counts —
+ * see [method@GLib.Variant.ref_sink].
+ *
+ * `GVariant` is completely threadsafe.  A `GVariant` instance can be
+ * concurrently accessed in any way from any number of threads without
+ * problems.
+ *
+ * `GVariant` is heavily optimised for dealing with data in serialized
+ * form.  It works particularly well with data located in memory-mapped
+ * files.  It can perform nearly all deserialization operations in a
+ * small constant time, usually touching only a single memory page.
+ * Serialized `GVariant` data can also be sent over the network.
+ *
+ * `GVariant` is largely compatible with D-Bus.  Almost all types of
+ * `GVariant` instances can be sent over D-Bus.  See [type@GLib.VariantType] for
+ * exceptions.  (However, `GVariant`’s serialization format is not the same
+ * as the serialization format of a D-Bus message body: use
+ * GDBusMessage, in the GIO library, for those.)
+ *
+ * For space-efficiency, the `GVariant` serialization format does not
+ * automatically include the variant’s length, type or endianness,
+ * which must either be implied from context (such as knowledge that a
+ * particular file format always contains a little-endian
+ * `G_VARIANT_TYPE_VARIANT` which occupies the whole length of the file)
+ * or supplied out-of-band (for instance, a length, type and/or endianness
+ * indicator could be placed at the beginning of a file, network message
+ * or network stream).
+ *
+ * A `GVariant`’s size is limited mainly by any lower level operating
+ * system constraints, such as the number of bits in `gsize`.  For
+ * example, it is reasonable to have a 2GB file mapped into memory
+ * with [struct@GLib.MappedFile], and call [ctor@GLib.Variant.new_from_data] on
+ * it.
+ *
+ * For convenience to C programmers, `GVariant` features powerful
+ * varargs-based value construction and destruction.  This feature is
+ * designed to be embedded in other libraries.
+ *
+ * There is a Python-inspired text language for describing `GVariant`
+ * values.  `GVariant` includes a printer for this language and a parser
+ * with type inferencing.
+ *
+ * ## Memory Use
+ *
+ * `GVariant` tries to be quite efficient with respect to memory use.
+ * This section gives a rough idea of how much memory is used by the
+ * current implementation.  The information here is subject to change
+ * in the future.
+ *
+ * The memory allocated by `GVariant` can be grouped into 4 broad
+ * purposes: memory for serialized data, memory for the type
+ * information cache, buffer management memory and memory for the
+ * `GVariant` structure itself.
+ *
+ * ## Serialized Data Memory
+ *
+ * This is the memory that is used for storing `GVariant` data in
+ * serialized form.  This is what would be sent over the network or
+ * what would end up on disk, not counting any indicator of the
+ * endianness, or of the length or type of the top-level variant.
+ *
+ * The amount of memory required to store a boolean is 1 byte. 16,
+ * 32 and 64 bit integers and double precision floating point numbers
+ * use their ‘natural’ size.  Strings (including object path and
+ * signature strings) are stored with a nul terminator, and as such
+ * use the length of the string plus 1 byte.
+ *
+ * ‘Maybe’ types use no space at all to represent the null value and
+ * use the same amount of space (sometimes plus one byte) as the
+ * equivalent non-maybe-typed value to represent the non-null case.
+ *
+ * Arrays use the amount of space required to store each of their
+ * members, concatenated.  Additionally, if the items stored in an
+ * array are not of a fixed-size (ie: strings, other arrays, etc)
+ * then an additional framing offset is stored for each item.  The
+ * size of this offset is either 1, 2 or 4 bytes depending on the
+ * overall size of the container.  Additionally, extra padding bytes
+ * are added as required for alignment of child values.
+ *
+ * Tuples (including dictionary entries) use the amount of space
+ * required to store each of their members, concatenated, plus one
+ * framing offset (as per arrays) for each non-fixed-sized item in
+ * the tuple, except for the last one.  Additionally, extra padding
+ * bytes are added as required for alignment of child values.
+ *
+ * Variants use the same amount of space as the item inside of the
+ * variant, plus 1 byte, plus the length of the type string for the
+ * item inside the variant.
+ *
+ * As an example, consider a dictionary mapping strings to variants.
+ * In the case that the dictionary is empty, 0 bytes are required for
+ * the serialization.
+ *
+ * If we add an item ‘width’ that maps to the int32 value of 500 then
+ * we will use 4 bytes to store the int32 (so 6 for the variant
+ * containing it) and 6 bytes for the string.  The variant must be
+ * aligned to 8 after the 6 bytes of the string, so that’s 2 extra
+ * bytes.  6 (string) + 2 (padding) + 6 (variant) is 14 bytes used
+ * for the dictionary entry.  An additional 1 byte is added to the
+ * array as a framing offset making a total of 15 bytes.
+ *
+ * If we add another entry, ‘title’ that maps to a nullable string
+ * that happens to have a value of null, then we use 0 bytes for the
+ * null value (and 3 bytes for the variant to contain it along with
+ * its type string) plus 6 bytes for the string.  Again, we need 2
+ * padding bytes.  That makes a total of 6 + 2 + 3 = 11 bytes.
+ *
+ * We now require extra padding between the two items in the array.
+ * After the 14 bytes of the first item, that’s 2 bytes required.
+ * We now require 2 framing offsets for an extra two
+ * bytes. 14 + 2 + 11 + 2 = 29 bytes to encode the entire two-item
+ * dictionary.
+ *
+ * ## Type Information Cache
+ *
+ * For each `GVariant` type that currently exists in the program a type
+ * information structure is kept in the type information cache.  The
+ * type information structure is required for rapid deserialization.
+ *
+ * Continuing with the above example, if a `GVariant` exists with the
+ * type `a{sv}` then a type information struct will exist for
+ * `a{sv}`, `{sv}`, `s`, and `v`.  Multiple uses of the same type
+ * will share the same type information.  Additionally, all
+ * single-digit types are stored in read-only static memory and do
+ * not contribute to the writable memory footprint of a program using
+ * `GVariant`.
+ *
+ * Aside from the type information structures stored in read-only
+ * memory, there are two forms of type information.  One is used for
+ * container types where there is a single element type: arrays and
+ * maybe types.  The other is used for container types where there
+ * are multiple element types: tuples and dictionary entries.
+ *
+ * Array type info structures are `6 * sizeof (void *)`, plus the
+ * memory required to store the type string itself.  This means that
+ * on 32-bit systems, the cache entry for `a{sv}` would require 30
+ * bytes of memory (plus allocation overhead).
+ *
+ * Tuple type info structures are `6 * sizeof (void *)`, plus `4 *
+ * sizeof (void *)` for each item in the tuple, plus the memory
+ * required to store the type string itself.  A 2-item tuple, for
+ * example, would have a type information structure that consumed
+ * writable memory in the size of `14 * sizeof (void *)` (plus type
+ * string)  This means that on 32-bit systems, the cache entry for
+ * `{sv}` would require 61 bytes of memory (plus allocation overhead).
+ *
+ * This means that in total, for our `a{sv}` example, 91 bytes of
+ * type information would be allocated.
+ *
+ * The type information cache, additionally, uses a [struct@GLib.HashTable] to
+ * store and look up the cached items and stores a pointer to this
+ * hash table in static storage.  The hash table is freed when there
+ * are zero items in the type cache.
+ *
+ * Although these sizes may seem large it is important to remember
+ * that a program will probably only have a very small number of
+ * different types of values in it and that only one type information
+ * structure is required for many different values of the same type.
+ *
+ * ## Buffer Management Memory
+ *
+ * `GVariant` uses an internal buffer management structure to deal
+ * with the various different possible sources of serialized data
+ * that it uses.  The buffer is responsible for ensuring that the
+ * correct call is made when the data is no longer in use by
+ * `GVariant`.  This may involve a [func@GLib.free] or
+ * even [method@GLib.MappedFile.unref].
+ *
+ * One buffer management structure is used for each chunk of
+ * serialized data.  The size of the buffer management structure
+ * is `4 * (void *)`.  On 32-bit systems, that’s 16 bytes.
+ *
+ * ## GVariant structure
+ *
+ * The size of a `GVariant` structure is `6 * (void *)`.  On 32-bit
+ * systems, that’s 24 bytes.
+ *
+ * `GVariant` structures only exist if they are explicitly created
+ * with API calls.  For example, if a `GVariant` is constructed out of
+ * serialized data for the example given above (with the dictionary)
+ * then although there are 9 individual values that comprise the
+ * entire dictionary (two keys, two values, two variants containing
+ * the values, two dictionary entries, plus the dictionary itself),
+ * only 1 `GVariant` instance exists — the one referring to the
+ * dictionary.
+ *
+ * If calls are made to start accessing the other values then
+ * `GVariant` instances will exist for those values only for as long
+ * as they are in use (ie: until you call [method@GLib.Variant.unref]).  The
+ * type information is shared.  The serialized data and the buffer
+ * management structure for that serialized data is shared by the
+ * child.
+ *
+ * ## Summary
+ *
+ * To put the entire example together, for our dictionary mapping
+ * strings to variants (with two entries, as given above), we are
+ * using 91 bytes of memory for type information, 29 bytes of memory
+ * for the serialized data, 16 bytes for buffer management and 24
+ * bytes for the `GVariant` instance, or a total of 160 bytes, plus
+ * allocation overhead.  If we were to use [method@GLib.Variant.get_child_value]
+ * to access the two dictionary entries, we would use an additional 48
+ * bytes.  If we were to have other dictionaries of the same type, we
+ * would use more memory for the serialized data and buffer
+ * management for those dictionaries, but the type information would
+ * be shared.
+ */
 export declare class Variant {
     ptr: unknown;
+    /**
+     * Creates a new #GVariant array from @children.
+     *
+     * `child_type` must be non-%NULL if `n_children` is zero.  Otherwise, the
+     * child type is determined by inspecting the first element of the
+     * `children` array.  If `child_type` is non-%NULL then it must be a
+     * definite type.
+     *
+     * The items of the array are taken from the `children` array.  No entry
+     * in the `children` array may be %NULL.
+     *
+     * All items in the array must have the same type, which must be the
+     * same as @child_type, if given.
+     *
+     * If the `children` are floating references (see g_variant_ref_sink()), the
+     * new instance takes ownership of them as if via g_variant_ref_sink().
+     * @param childType - the element type of the new array
+     * @param children - an array of
+     * @param nChildren - the length of @children
+     */
     constructor(nChildren: number, childType?: VariantType | null, children?: Variant[] | null);
     constructor(_args: unknown[]);
+    /**
+     * Creates a new boolean #GVariant instance -- either %TRUE or %FALSE.
+     * @param value - a #gboolean value
+     */
     static newBoolean(value: boolean): Variant;
+    /**
+     * Creates a new byte #GVariant instance.
+     * @param value - a #guint8 value
+     */
     static newByte(value: number): Variant;
+    /**
+     * Creates an array-of-bytes #GVariant with the contents of @string.
+     * This function is just like g_variant_new_string() except that the
+     * string need not be valid UTF-8.
+     *
+     * The nul terminator character at the end of the string is stored in
+     * the array.
+     * @param string - a normal
+     */
     static newBytestring(string: number[]): Variant;
+    /**
+     * Constructs an array of bytestring #GVariant from the given array of
+     * strings.
+     *
+     * If `length` is -1 then `strv` is %NULL-terminated.
+     * @param strv - an array of strings
+     * @param length - the length of @strv, or -1
+     */
     static newBytestringArray(strv: string[], length: number): Variant;
+    /**
+     * Creates a new dictionary entry #GVariant. `key` and `value` must be
+     * non-%NULL. `key` must be a value of a basic type (ie: not a container).
+     *
+     * If the `key` or `value` are floating references (see g_variant_ref_sink()),
+     * the new instance takes ownership of them as if via g_variant_ref_sink().
+     * @param key - a basic #GVariant, the key
+     * @param value - a #GVariant, the value
+     */
     static newDictEntry(key: Variant, value: Variant): Variant;
+    /**
+     * Creates a new double #GVariant instance.
+     * @param value - a #gdouble floating point value
+     */
     static newDouble(value: number): Variant;
+    /**
+     * Constructs a new array #GVariant instance, where the elements are
+     * of `element_type` type.
+     *
+     * `elements` must be an array with fixed-sized elements.  Numeric types are
+     * fixed-size as are tuples containing only other fixed-sized types.
+     *
+     * `element_size` must be the size of a single element in the array.
+     * For example, if calling this function for an array of 32-bit integers,
+     * you might say sizeof(gint32). This value isn't used except for the purpose
+     * of a double-check that the form of the serialized data matches the caller's
+     * expectation.
+     *
+     * `n_elements` must be the length of the `elements` array.
+     * @param elementType - the #GVariantType of each element
+     * @param elements - a pointer to the fixed array of contiguous elements
+     * @param nElements - the number of elements
+     * @param elementSize - the size of each element
+     */
     static newFixedArray(elementType: VariantType, nElements: number, elementSize: number, elements?: number | null): Variant;
+    /**
+     * Constructs a new serialized-mode #GVariant instance.  This is the
+     * inner interface for creation of new serialized values that gets
+     * called from various functions in gvariant.c.
+     *
+     * A reference is taken on @bytes.
+     *
+     * The data in `bytes` must be aligned appropriately for the `type` being loaded.
+     * Otherwise this function will internally create a copy of the memory (since
+     * GLib 2.60) or (in older versions) fail and exit the process.
+     * @param type - a #GVariantType
+     * @param bytes - a #GBytes
+     * @param trusted - if the contents of `bytes` are trusted
+     */
     static newFromBytes(type: VariantType, bytes: Bytes, trusted: boolean): Variant;
+    /**
+     * Creates a new #GVariant instance from serialized data.
+     *
+     * `type` is the type of #GVariant instance that will be constructed.
+     * The interpretation of `data` depends on knowing the type.
+     *
+     * `data` is not modified by this function and must remain valid with an
+     * unchanging value until such a time as `notify` is called with
+     * @user_data.  If the contents of `data` change before that time then
+     * the result is undefined.
+     *
+     * If `data` is trusted to be serialized data in normal form then
+     * `trusted` should be %TRUE.  This applies to serialized data created
+     * within this process or read from a trusted location on the disk (such
+     * as a file installed in /usr/lib alongside your application).  You
+     * should set trusted to %FALSE if `data` is read from the network, a
+     * file in the user's home directory, etc.
+     *
+     * If `data` was not stored in this machine's native endianness, any multi-byte
+     * numeric values in the returned variant will also be in non-native
+     * endianness. g_variant_byteswap() can be used to recover the original values.
+     *
+     * `notify` will be called with `user_data` when `data` is no longer
+     * needed.  The exact time of this call is unspecified and might even be
+     * before this function returns.
+     *
+     * Note: `data` must be backed by memory that is aligned appropriately for the
+     * `type` being loaded. Otherwise this function will internally create a copy of
+     * the memory (since GLib 2.60) or (in older versions) fail and exit the
+     * process.
+     * @param type - a definite #GVariantType
+     * @param data - the serialized data
+     * @param size - the size of @data
+     * @param trusted - %TRUE if `data` is definitely in normal form
+     * @param notify - function to call when `data` is no longer needed
+     * @param userData - data for @notify
+     */
     static newFromData(type: VariantType, data: number[], size: number, trusted: boolean, notify: (...args: unknown[]) => unknown, userData?: number | null): Variant;
+    /**
+     * Creates a new handle #GVariant instance.
+     *
+     * By convention, handles are indexes into an array of file descriptors
+     * that are sent alongside a D-Bus message.  If you're not interacting
+     * with D-Bus, you probably don't need them.
+     * @param value - a #gint32 value
+     */
     static newHandle(value: number): Variant;
+    /**
+     * Creates a new int16 #GVariant instance.
+     * @param value - a #gint16 value
+     */
     static newInt16(value: number): Variant;
+    /**
+     * Creates a new int32 #GVariant instance.
+     * @param value - a #gint32 value
+     */
     static newInt32(value: number): Variant;
+    /**
+     * Creates a new int64 #GVariant instance.
+     * @param value - a #gint64 value
+     */
     static newInt64(value: number): Variant;
+    /**
+     * Depending on if `child` is %NULL, either wraps `child` inside of a
+     * maybe container or creates a Nothing instance for the given @type.
+     *
+     * At least one of `child_type` and `child` must be non-%NULL.
+     * If `child_type` is non-%NULL then it must be a definite type.
+     * If they are both non-%NULL then `child_type` must be the type
+     * of @child.
+     *
+     * If `child` is a floating reference (see g_variant_ref_sink()), the new
+     * instance takes ownership of @child.
+     * @param childType - the #GVariantType of the child, or %NULL
+     * @param child - the child value, or %NULL
+     */
     static newMaybe(childType?: VariantType | null, child?: Variant | null): Variant;
+    /**
+     * Creates a D-Bus object path #GVariant with the contents of @object_path.
+     * `object_path` must be a valid D-Bus object path.  Use
+     * g_variant_is_object_path() if you're not sure.
+     * @param objectPath - a normal C nul-terminated string
+     */
     static newObjectPath(objectPath: string): Variant;
+    /**
+     * Constructs an array of object paths #GVariant from the given array of
+     * strings.
+     *
+     * Each string must be a valid #GVariant object path; see
+     * g_variant_is_object_path().
+     *
+     * If `length` is -1 then `strv` is %NULL-terminated.
+     * @param strv - an array of strings
+     * @param length - the length of @strv, or -1
+     */
     static newObjv(strv: string[], length: number): Variant;
+    /**
+     * Creates a D-Bus type signature #GVariant with the contents of
+     * @string.  `string` must be a valid D-Bus type signature.  Use
+     * g_variant_is_signature() if you're not sure.
+     * @param signature - a normal C nul-terminated string
+     */
     static newSignature(signature: string): Variant;
+    /**
+     * Creates a string #GVariant with the contents of @string.
+     *
+     * `string` must be valid UTF-8, and must not be %NULL. To encode
+     * potentially-%NULL strings, use g_variant_new() with `ms` as the
+     * format string.
+     * @param string - a normal UTF-8 nul-terminated string
+     */
     static newString(string: string): Variant;
+    /**
+     * Constructs an array of strings #GVariant from the given array of
+     * strings.
+     *
+     * If `length` is -1 then `strv` is %NULL-terminated.
+     * @param strv - an array of strings
+     * @param length - the length of @strv, or -1
+     */
     static newStrv(strv: string[], length: number): Variant;
+    /**
+     * Creates a new tuple #GVariant out of the items in @children.  The
+     * type is determined from the types of @children.  No entry in the
+     * `children` array may be %NULL.
+     *
+     * If `n_children` is 0 then the unit tuple is constructed.
+     *
+     * If the `children` are floating references (see g_variant_ref_sink()), the
+     * new instance takes ownership of them as if via g_variant_ref_sink().
+     * @param children - the items to make the tuple out of
+     * @param nChildren - the length of @children
+     */
     static newTuple(children: Variant[], nChildren: number): Variant;
+    /**
+     * Creates a new uint16 #GVariant instance.
+     * @param value - a #guint16 value
+     */
     static newUint16(value: number): Variant;
+    /**
+     * Creates a new uint32 #GVariant instance.
+     * @param value - a #guint32 value
+     */
     static newUint32(value: number): Variant;
+    /**
+     * Creates a new uint64 #GVariant instance.
+     * @param value - a #guint64 value
+     */
     static newUint64(value: number): Variant;
+    /**
+     * Boxes @value.  The result is a #GVariant instance representing a
+     * variant containing the original value.
+     *
+     * If `child` is a floating reference (see g_variant_ref_sink()), the new
+     * instance takes ownership of @child.
+     * @param value - a #GVariant instance
+     */
     static newVariant(value: Variant): Variant;
     protected createPtr(_args: unknown[]): unknown;
+    /**
+     * Determines if a given string is a valid D-Bus object path.  You
+     * should ensure that a string is a valid D-Bus object path before
+     * passing it to g_variant_new_object_path().
+     *
+     * A valid object path starts with `/` followed by zero or more
+     * sequences of characters separated by `/` characters.  Each sequence
+     * must contain only the characters `[A-Z][a-z][0-9]_`.  No sequence
+     * (including the one following the final `/` character) may be empty.
+     * @param string - a normal C nul-terminated string
+     */
     static isObjectPath(string: string): boolean;
+    /**
+     * Determines if a given string is a valid D-Bus type signature.  You
+     * should ensure that a string is a valid D-Bus type signature before
+     * passing it to g_variant_new_signature().
+     *
+     * D-Bus type signatures consist of zero or more definite #GVariantType
+     * strings in sequence.
+     * @param string - a normal C nul-terminated string
+     */
     static isSignature(string: string): boolean;
+    /**
+     * Parses a #GVariant from a text representation.
+     *
+     * A single #GVariant is parsed from the content of @text.
+     *
+     * The format is described here.
+     *
+     * The memory at `limit` will never be accessed and the parser behaves as
+     * if the character at `limit` is the nul terminator.  This has the
+     * effect of bounding @text.
+     *
+     * If `endptr` is non-%NULL then `text` is permitted to contain data
+     * following the value that this function parses and `endptr` will be
+     * updated to point to the first character past the end of the text
+     * parsed by this function.  If `endptr` is %NULL and there is extra data
+     * then an error is returned.
+     *
+     * If `type` is non-%NULL then the value will be parsed to have that
+     * type.  This may result in additional parse errors (in the case that
+     * the parsed value doesn't fit the type) but may also result in fewer
+     * errors (in the case that the type would have been ambiguous, such as
+     * with empty arrays).
+     *
+     * In the event that the parsing is successful, the resulting #GVariant
+     * is returned. It is never floating, and must be freed with
+     * [method@GLib.Variant.unref].
+     *
+     * In case of any error, %NULL will be returned.  If `error` is non-%NULL
+     * then it will be set to reflect the error that occurred.
+     *
+     * Officially, the language understood by the parser is “any string
+     * produced by [method@GLib.Variant.print]”. This explicitly includes
+     * `g_variant_print()`’s annotated types like `int64 -1000`.
+     *
+     * There may be implementation specific restrictions on deeply nested values,
+     * which would result in a %G_VARIANT_PARSE_ERROR_RECURSION error. #GVariant is
+     * guaranteed to handle nesting up to at least 64 levels.
+     * @param type - a #GVariantType, or %NULL
+     * @param text - a string containing a GVariant in text form
+     * @param limit - a pointer to the end of @text, or %NULL
+     * @param endptr - a location to store the end pointer, or %NULL
+     */
     static parse(text: string, type?: VariantType | null, limit?: string | null, endptr?: string | null): Variant;
+    /**
+     * Pretty-prints a message showing the context of a #GVariant parse
+     * error within the string for which parsing was attempted.
+     *
+     * The resulting string is suitable for output to the console or other
+     * monospace media where newlines are treated in the usual way.
+     *
+     * The message will typically look something like one of the following:
+     *
+     * |[
+     * unterminated string constant:
+     * (1, 2, 3, 'abc
+     * ^^^^
+     * ]|
+     *
+     * or
+     *
+     * |[
+     * unable to find a common type:
+     * [1, 2, 3, 'str']
+     * ^        ^^^^^
+     * ]|
+     *
+     * The format of the message may change in a future version.
+     *
+     * `error` must have come from a failed attempt to g_variant_parse() and
+     * `source_str` must be exactly the same string that caused the error.
+     * If `source_str` was not nul-terminated when you passed it to
+     * g_variant_parse() then you must add nul termination before using this
+     * function.
+     * @param error - a #GError from the #GVariantParseError domain
+     * @param sourceStr - the string that was given to the parser
+     */
     static parseErrorPrintContext(error: GError, sourceStr: string): string;
     static parseErrorQuark(): number;
+    /**
+     * Same as g_variant_error_quark().
+     */
     static parserGetErrorQuark(): number;
+    /**
+     * Performs a byteswapping operation on the contents of @value.  The
+     * result is that all multi-byte numeric data contained in `value` is
+     * byteswapped.  That includes 16, 32, and 64bit signed and unsigned
+     * integers as well as file handles and double precision floating point
+     * values.
+     *
+     * This function is an identity mapping on any value that does not
+     * contain multi-byte numeric data.  That include strings, booleans,
+     * bytes and containers containing only these things (recursively).
+     *
+     * While this function can safely handle untrusted, non-normal data, it is
+     * recommended to check whether the input is in normal form beforehand, using
+     * g_variant_is_normal_form(), and to reject non-normal inputs if your
+     * application can be strict about what inputs it rejects.
+     *
+     * The returned value is always in normal form and is marked as trusted.
+     * A full, not floating, reference is returned.
+     */
     byteswap(): Variant;
+    /**
+     * Checks if calling g_variant_get() with `format_string` on `value` would
+     * be valid from a type-compatibility standpoint.  `format_string` is
+     * assumed to be a valid format string (from a syntactic standpoint).
+     *
+     * If `copy_only` is %TRUE then this function additionally checks that it
+     * would be safe to call g_variant_unref() on `value` immediately after
+     * the call to g_variant_get() without invalidating the result.  This is
+     * only possible if deep copies are made (ie: there are no pointers to
+     * the data inside of the soon-to-be-freed #GVariant instance).  If this
+     * check fails then a g_critical() is printed and %FALSE is returned.
+     *
+     * This function is meant to be used by functions that wish to provide
+     * varargs accessors to #GVariant values of uncertain values (eg:
+     * g_variant_lookup() or g_menu_model_get_item_attribute()).
+     * @param formatString - a valid #GVariant format string
+     * @param copyOnly - %TRUE to ensure the format string makes deep copies
+     */
     checkFormatString(formatString: string, copyOnly: boolean): boolean;
+    /**
+     * Classifies `value` according to its top-level type.
+     */
     classify(): VariantClass;
+    /**
+     * Compares `one` and @two.
+     *
+     * The types of `one` and `two` are #gconstpointer only to allow use of
+     * this function with #GTree, #GPtrArray, etc.  They must each be a
+     * #GVariant.
+     *
+     * Comparison is only defined for basic types (ie: booleans, numbers,
+     * strings).  For booleans, %FALSE is less than %TRUE.  Numbers are
+     * ordered in the usual way.  Strings are in ASCII lexographical order.
+     *
+     * It is a programmer error to attempt to compare container values or
+     * two values that have types that are not exactly equal.  For example,
+     * you cannot compare a 32-bit signed integer with a 32-bit unsigned
+     * integer.  Also note that this function is not particularly
+     * well-behaved when it comes to comparison of doubles; in particular,
+     * the handling of incomparable values (ie: NaN) is undefined.
+     *
+     * If you only require an equality comparison, g_variant_equal() is more
+     * general.
+     * @param two - a #GVariant instance of the same type
+     */
     compare(two: Variant): number;
+    /**
+     * Similar to g_variant_get_bytestring() except that instead of
+     * returning a constant string, the string is duplicated.
+     *
+     * The return value must be freed using g_free().
+     * @param length - a pointer to a #gsize, to store
+     */
     dupBytestring(length?: Ref<number> | null): number[];
+    /**
+     * Gets the contents of an array of array of bytes #GVariant.  This call
+     * makes a deep copy; the return result should be released with
+     * g_strfreev().
+     *
+     * If `length` is non-%NULL then the number of elements in the result is
+     * stored there.  In any case, the resulting array will be
+     * %NULL-terminated.
+     *
+     * For an empty array, `length` will be set to 0 and a pointer to a
+     * %NULL pointer will be returned.
+     * @param length - the length of the result, or %NULL
+     */
     dupBytestringArray(length?: Ref<number> | null): string[];
+    /**
+     * Gets the contents of an array of object paths #GVariant.  This call
+     * makes a deep copy; the return result should be released with
+     * g_strfreev().
+     *
+     * If `length` is non-%NULL then the number of elements in the result
+     * is stored there.  In any case, the resulting array will be
+     * %NULL-terminated.
+     *
+     * For an empty array, `length` will be set to 0 and a pointer to a
+     * %NULL pointer will be returned.
+     * @param length - the length of the result, or %NULL
+     */
     dupObjv(length?: Ref<number> | null): string[];
+    /**
+     * Similar to g_variant_get_string() except that instead of returning
+     * a constant string, the string is duplicated.
+     *
+     * The string will always be UTF-8 encoded.
+     *
+     * The return value must be freed using g_free().
+     * @param length - a pointer to a #gsize, to store the length
+     */
     dupString(length: Ref<number>): string;
+    /**
+     * Gets the contents of an array of strings #GVariant.  This call
+     * makes a deep copy; the return result should be released with
+     * g_strfreev().
+     *
+     * If `length` is non-%NULL then the number of elements in the result
+     * is stored there.  In any case, the resulting array will be
+     * %NULL-terminated.
+     *
+     * For an empty array, `length` will be set to 0 and a pointer to a
+     * %NULL pointer will be returned.
+     * @param length - the length of the result, or %NULL
+     */
     dupStrv(length?: Ref<number> | null): string[];
+    /**
+     * Checks if `one` and `two` have the same type and value.
+     *
+     * The types of `one` and `two` are #gconstpointer only to allow use of
+     * this function with #GHashTable.  They must each be a #GVariant.
+     * @param two - a #GVariant instance
+     */
     equal(two: Variant): boolean;
+    /**
+     * Returns the boolean value of @value.
+     *
+     * It is an error to call this function with a `value` of any type
+     * other than %G_VARIANT_TYPE_BOOLEAN.
+     */
     getBoolean(): boolean;
+    /**
+     * Returns the byte value of @value.
+     *
+     * It is an error to call this function with a `value` of any type
+     * other than %G_VARIANT_TYPE_BYTE.
+     */
     getByte(): number;
+    /**
+     * Returns the string value of a #GVariant instance with an
+     * array-of-bytes type.  The string has no particular encoding.
+     *
+     * If the array does not end with a nul terminator character, the empty
+     * string is returned.  For this reason, you can always trust that a
+     * non-%NULL nul-terminated string will be returned by this function.
+     *
+     * If the array contains a nul terminator character somewhere other than
+     * the last byte then the returned string is the string, up to the first
+     * such nul character.
+     *
+     * g_variant_get_fixed_array() should be used instead if the array contains
+     * arbitrary data that could not be nul-terminated or could contain nul bytes.
+     *
+     * It is an error to call this function with a `value` that is not an
+     * array of bytes.
+     *
+     * The return value remains valid as long as `value` exists.
+     */
     getBytestring(): number[];
+    /**
+     * Gets the contents of an array of array of bytes #GVariant.  This call
+     * makes a shallow copy; the return result should be released with
+     * g_free(), but the individual strings must not be modified.
+     *
+     * If `length` is non-%NULL then the number of elements in the result is
+     * stored there.  In any case, the resulting array will be
+     * %NULL-terminated.
+     *
+     * For an empty array, `length` will be set to 0 and a pointer to a
+     * %NULL pointer will be returned.
+     * @param length - the length of the result, or %NULL
+     */
     getBytestringArray(length?: Ref<number> | null): string[];
+    /**
+     * Reads a child item out of a container #GVariant instance.  This
+     * includes variants, maybes, arrays, tuples and dictionary
+     * entries.  It is an error to call this function on any other type of
+     * #GVariant.
+     *
+     * It is an error if `index_` is greater than the number of child items
+     * in the container.  See g_variant_n_children().
+     *
+     * The returned value is never floating.  You should free it with
+     * g_variant_unref() when you're done with it.
+     *
+     * Note that values borrowed from the returned child are not guaranteed to
+     * still be valid after the child is freed even if you still hold a reference
+     * to @value, if `value` has not been serialized at the time this function is
+     * called. To avoid this, you can serialize `value` by calling
+     * g_variant_get_data() and optionally ignoring the return value.
+     *
+     * There may be implementation specific restrictions on deeply nested values,
+     * which would result in the unit tuple being returned as the child value,
+     * instead of further nested children. #GVariant is guaranteed to handle
+     * nesting up to at least 64 levels.
+     *
+     * This function is O(1).
+     * @param index_ - the index of the child to fetch
+     */
     getChildValue(index_: number): Variant;
+    /**
+     * Returns a pointer to the serialized form of a #GVariant instance.
+     * The returned data may not be in fully-normalised form if read from an
+     * untrusted source.  The returned data must not be freed; it remains
+     * valid for as long as `value` exists.
+     *
+     * If `value` is a fixed-sized value that was deserialized from a
+     * corrupted serialized container then %NULL may be returned.  In this
+     * case, the proper thing to do is typically to use the appropriate
+     * number of nul bytes in place of @value.  If `value` is not fixed-sized
+     * then %NULL is never returned.
+     *
+     * In the case that `value` is already in serialized form, this function
+     * is O(1).  If the value is not already in serialized form,
+     * serialization occurs implicitly and is approximately O(n) in the size
+     * of the result.
+     *
+     * To deserialize the data returned by this function, in addition to the
+     * serialized data, you must know the type of the #GVariant, and (if the
+     * machine might be different) the endianness of the machine that stored
+     * it. As a result, file formats or network messages that incorporate
+     * serialized #GVariants must include this information either
+     * implicitly (for instance "the file always contains a
+     * %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or
+     * explicitly (by storing the type and/or endianness in addition to the
+     * serialized data).
+     */
     getData(): number | null;
+    /**
+     * Returns a pointer to the serialized form of a #GVariant instance.
+     * The semantics of this function are exactly the same as
+     * g_variant_get_data(), except that the returned #GBytes holds
+     * a reference to the variant data.
+     */
     getDataAsBytes(): Bytes;
+    /**
+     * Returns the double precision floating point value of @value.
+     *
+     * It is an error to call this function with a `value` of any type
+     * other than %G_VARIANT_TYPE_DOUBLE.
+     */
     getDouble(): number;
+    /**
+     * Returns the 32-bit signed integer value of @value.
+     *
+     * It is an error to call this function with a `value` of any type other
+     * than %G_VARIANT_TYPE_HANDLE.
+     *
+     * By convention, handles are indexes into an array of file descriptors
+     * that are sent alongside a D-Bus message.  If you're not interacting
+     * with D-Bus, you probably don't need them.
+     */
     getHandle(): number;
+    /**
+     * Returns the 16-bit signed integer value of @value.
+     *
+     * It is an error to call this function with a `value` of any type
+     * other than %G_VARIANT_TYPE_INT16.
+     */
     getInt16(): number;
+    /**
+     * Returns the 32-bit signed integer value of @value.
+     *
+     * It is an error to call this function with a `value` of any type
+     * other than %G_VARIANT_TYPE_INT32.
+     */
     getInt32(): number;
+    /**
+     * Returns the 64-bit signed integer value of @value.
+     *
+     * It is an error to call this function with a `value` of any type
+     * other than %G_VARIANT_TYPE_INT64.
+     */
     getInt64(): number;
+    /**
+     * Given a maybe-typed #GVariant instance, extract its value.  If the
+     * value is Nothing, then this function returns %NULL.
+     */
     getMaybe(): Variant | null;
+    /**
+     * Gets a #GVariant instance that has the same value as `value` and is
+     * trusted to be in normal form.
+     *
+     * If `value` is already trusted to be in normal form then a new
+     * reference to `value` is returned.
+     *
+     * If `value` is not already trusted, then it is scanned to check if it
+     * is in normal form.  If it is found to be in normal form then it is
+     * marked as trusted and a new reference to it is returned.
+     *
+     * If `value` is found not to be in normal form then a new trusted
+     * #GVariant is created with the same value as @value. The non-normal parts of
+     * `value` will be replaced with default values which are guaranteed to be in
+     * normal form.
+     *
+     * It makes sense to call this function if you've received #GVariant
+     * data from untrusted sources and you want to ensure your serialized
+     * output is definitely in normal form.
+     *
+     * If `value` is already in normal form, a new reference will be returned
+     * (which will be floating if `value` is floating). If it is not in normal form,
+     * the newly created #GVariant will be returned with a single non-floating
+     * reference. Typically, g_variant_take_ref() should be called on the return
+     * value from this function to guarantee ownership of a single non-floating
+     * reference to it.
+     */
     getNormalForm(): Variant;
+    /**
+     * Gets the contents of an array of object paths #GVariant.  This call
+     * makes a shallow copy; the return result should be released with
+     * g_free(), but the individual strings must not be modified.
+     *
+     * If `length` is non-%NULL then the number of elements in the result
+     * is stored there.  In any case, the resulting array will be
+     * %NULL-terminated.
+     *
+     * For an empty array, `length` will be set to 0 and a pointer to a
+     * %NULL pointer will be returned.
+     * @param length - the length of the result, or %NULL
+     */
     getObjv(length?: Ref<number> | null): string[];
+    /**
+     * Determines the number of bytes that would be required to store `value` with g_variant_store().
+     *
+     * If `value` has a fixed-sized type then this function always returned
+     * that fixed size.
+     *
+     * In the case that `value` is already in serialized form or the size has
+     * already been calculated (ie: this function has been called before)
+     * then this function is O(1).  Otherwise, the size is calculated, an
+     * operation which is approximately O(n) in the number of values
+     * involved.
+     */
     getSize(): number;
+    /**
+     * Returns the string value of a #GVariant instance with a string
+     * type.  This includes the types %G_VARIANT_TYPE_STRING,
+     * %G_VARIANT_TYPE_OBJECT_PATH and %G_VARIANT_TYPE_SIGNATURE.
+     *
+     * The string will always be UTF-8 encoded, will never be %NULL, and will never
+     * contain nul bytes.
+     *
+     * If `length` is non-%NULL then the length of the string (in bytes) is
+     * returned there.  For trusted values, this information is already
+     * known.  Untrusted values will be validated and, if valid, a strlen() will be
+     * performed. If invalid, a default value will be returned — for
+     * %G_VARIANT_TYPE_OBJECT_PATH, this is `"/"`, and for other types it is the
+     * empty string.
+     *
+     * It is an error to call this function with a `value` of any type
+     * other than those three.
+     *
+     * The return value remains valid as long as `value` exists.
+     * @param length - a pointer to a #gsize,
+     */
     getString(length?: Ref<number> | null): string;
+    /**
+     * Gets the contents of an array of strings #GVariant.  This call
+     * makes a shallow copy; the return result should be released with
+     * g_free(), but the individual strings must not be modified.
+     *
+     * If `length` is non-%NULL then the number of elements in the result
+     * is stored there.  In any case, the resulting array will be
+     * %NULL-terminated.
+     *
+     * For an empty array, `length` will be set to 0 and a pointer to a
+     * %NULL pointer will be returned.
+     * @param length - the length of the result, or %NULL
+     */
     getStrv(length?: Ref<number> | null): string[];
+    /**
+     * Determines the type of @value.
+     *
+     * The return value is valid for the lifetime of `value` and must not
+     * be freed.
+     */
     getType(): VariantType;
+    /**
+     * Returns the type string of @value.  Unlike the result of calling
+     * g_variant_type_peek_string(), this string is nul-terminated.  This
+     * string belongs to #GVariant and must not be freed.
+     */
     getTypeString(): string;
+    /**
+     * Returns the 16-bit unsigned integer value of @value.
+     *
+     * It is an error to call this function with a `value` of any type
+     * other than %G_VARIANT_TYPE_UINT16.
+     */
     getUint16(): number;
+    /**
+     * Returns the 32-bit unsigned integer value of @value.
+     *
+     * It is an error to call this function with a `value` of any type
+     * other than %G_VARIANT_TYPE_UINT32.
+     */
     getUint32(): number;
+    /**
+     * Returns the 64-bit unsigned integer value of @value.
+     *
+     * It is an error to call this function with a `value` of any type
+     * other than %G_VARIANT_TYPE_UINT64.
+     */
     getUint64(): number;
+    /**
+     * Unboxes @value.  The result is the #GVariant instance that was
+     * contained in @value.
+     */
     getVariant(): Variant;
+    /**
+     * Generates a hash value for a #GVariant instance.
+     *
+     * The output of this function is guaranteed to be the same for a given
+     * value only per-process.  It may change between different processor
+     * architectures or even different versions of GLib.  Do not use this
+     * function as a basis for building protocols or file formats.
+     *
+     * The type of `value` is #gconstpointer only to allow use of this
+     * function with #GHashTable.  `value` must be a #GVariant.
+     */
     hash(): number;
+    /**
+     * Checks if `value` is a container.
+     */
     isContainer(): boolean;
+    /**
+     * Checks whether `value` has a floating reference count.
+     *
+     * This function should only ever be used to assert that a given variant
+     * is or is not floating, or for debug purposes. To acquire a reference
+     * to a variant that might be floating, always use g_variant_ref_sink()
+     * or g_variant_take_ref().
+     *
+     * See g_variant_ref_sink() for more information about floating reference
+     * counts.
+     */
     isFloating(): boolean;
+    /**
+     * Checks if `value` is in normal form.
+     *
+     * The main reason to do this is to detect if a given chunk of
+     * serialized data is in normal form: load the data into a #GVariant
+     * using g_variant_new_from_data() and then use this function to
+     * check.
+     *
+     * If `value` is found to be in normal form then it will be marked as
+     * being trusted.  If the value was already marked as being trusted then
+     * this function will immediately return %TRUE.
+     *
+     * There may be implementation specific restrictions on deeply nested values.
+     * GVariant is guaranteed to handle nesting up to at least 64 levels.
+     */
     isNormalForm(): boolean;
+    /**
+     * Checks if a value has a type matching the provided type.
+     * @param type - a #GVariantType
+     */
     isOfType(type: VariantType): boolean;
+    /**
+     * Looks up a value in a dictionary #GVariant.
+     *
+     * This function works with dictionaries of the type a{s*} (and equally
+     * well with type a{o*}, but we only further discuss the string case
+     * for sake of clarity).
+     *
+     * In the event that `dictionary` has the type a{sv}, the `expected_type` string specifies what type of value is expected to be inside of the
+     * variant. If the value inside the variant has a different type then
+     * %NULL is returned. In the event that `dictionary` has a value type other
+     * than v then `expected_type` must directly match the value type and it is
+     * used to unpack the value directly or an error occurs.
+     *
+     * In either case, if `key` is not found in @dictionary, %NULL is returned.
+     *
+     * If the key is found and the value has the correct type, it is
+     * returned.  If `expected_type` was specified then any non-%NULL return
+     * value will have this type.
+     *
+     * This function is currently implemented with a linear scan.  If you
+     * plan to do many lookups then #GVariantDict may be more efficient.
+     * @param key - the key to look up in the dictionary
+     * @param expectedType - a #GVariantType, or %NULL
+     */
     lookupValue(key: string, expectedType?: VariantType | null): Variant;
+    /**
+     * Determines the number of children in a container #GVariant instance.
+     * This includes variants, maybes, arrays, tuples and dictionary
+     * entries.  It is an error to call this function on any other type of
+     * #GVariant.
+     *
+     * For variants, the return value is always 1.  For values with maybe
+     * types, it is always zero or one.  For arrays, it is the length of the
+     * array.  For tuples it is the number of tuple items (which depends
+     * only on the type).  For dictionary entries, it is always 2
+     *
+     * This function is O(1).
+     */
     nChildren(): number;
+    /**
+     * Pretty-prints `value` in the format understood by g_variant_parse().
+     *
+     * The format is described here.
+     *
+     * If `type_annotate` is %TRUE, then type information is included in
+     * the output.
+     * @param typeAnnotate - %TRUE if type information should be included in
+     */
     print(typeAnnotate: boolean): string;
+    /**
+     * Increases the reference count of @value.
+     */
     ref(): Variant;
+    /**
+     * #GVariant uses a floating reference count system.  All functions with
+     * names starting with `g_variant_new_` return floating
+     * references.
+     *
+     * Calling g_variant_ref_sink() on a #GVariant with a floating reference
+     * will convert the floating reference into a full reference.  Calling
+     * g_variant_ref_sink() on a non-floating #GVariant results in an
+     * additional normal reference being added.
+     *
+     * In other words, if the `value` is floating, then this call "assumes
+     * ownership" of the floating reference, converting it to a normal
+     * reference.  If the `value` is not floating, then this call adds a
+     * new normal reference increasing the reference count by one.
+     *
+     * All calls that result in a #GVariant instance being inserted into a
+     * container will call g_variant_ref_sink() on the instance.  This means
+     * that if the value was just created (and has only its floating
+     * reference) then the container will assume sole ownership of the value
+     * at that point and the caller will not need to unreference it.  This
+     * makes certain common styles of programming much easier while still
+     * maintaining normal refcounting semantics in situations where values
+     * are not floating.
+     */
     refSink(): Variant;
+    /**
+     * Stores the serialized form of `value` at @data.  `data` should be
+     * large enough.  See g_variant_get_size().
+     *
+     * The stored data is in machine native byte order but may not be in
+     * fully-normalised form if read from an untrusted source.  See
+     * g_variant_get_normal_form() for a solution.
+     *
+     * As with g_variant_get_data(), to be able to deserialize the
+     * serialized variant successfully, its type and (if the destination
+     * machine might be different) its endianness must also be available.
+     *
+     * This function is approximately O(n) in the size of @data.
+     * @param data - the location to store the serialized data at
+     */
     store(data: number): void;
+    /**
+     * If `value` is floating, sink it.  Otherwise, do nothing.
+     *
+     * Typically you want to use g_variant_ref_sink() in order to
+     * automatically do the correct thing with respect to floating or
+     * non-floating references, but there is one specific scenario where
+     * this function is helpful.
+     *
+     * The situation where this function is helpful is when creating an API
+     * that allows the user to provide a callback function that returns a
+     * #GVariant.  We certainly want to allow the user the flexibility to
+     * return a non-floating reference from this callback (for the case
+     * where the value that is being returned already exists).
+     *
+     * At the same time, the style of the #GVariant API makes it likely that
+     * for newly-created #GVariant instances, the user can be saved some
+     * typing if they are allowed to return a #GVariant with a floating
+     * reference.
+     *
+     * Using this function on the return value of the user's callback allows
+     * the user to do whichever is more convenient for them.  The caller
+     * will always receives exactly one full reference to the value: either
+     * the one that was returned in the first place, or a floating reference
+     * that has been converted to a full reference.
+     *
+     * This function has an odd interaction when combined with
+     * g_variant_ref_sink() running at the same time in another thread on
+     * the same #GVariant instance.  If g_variant_ref_sink() runs first then
+     * the result will be that the floating reference is converted to a hard
+     * reference.  If g_variant_take_ref() runs first then the result will
+     * be that the floating reference is converted to a hard reference and
+     * an additional reference on top of that one is added.  It is best to
+     * avoid this situation.
+     */
     takeRef(): Variant;
+    /**
+     * Decreases the reference count of @value.  When its reference count
+     * drops to 0, the memory used by the variant is freed.
+     */
     unref(): void;
 }