@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/glib/markup-parse-context.js

@@ -1,5 +1,12 @@
 import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
+/**
+ * A parse context is used to parse a stream of bytes that
+ * you expect to contain marked-up text.
+ *
+ * See g_markup_parse_context_new(), #GMarkupParser, and so
+ * on for more details.
+ */
 export class MarkupParseContext {
     ptr;
     constructor(...args) {
@@ -28,6 +35,13 @@ export class MarkupParseContext {
             },
         ], { type: "boxed", borrowed: true, innerType: "GMarkupParseContext" });
     }
+    /**
+     * Signals to the #GMarkupParseContext that all data has been
+     * fed into the parse context with g_markup_parse_context_parse().
+     *
+     * This function reports an error if the document isn't complete,
+     * for example if elements are still open.
+     */
     endParse() {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_markup_parse_context_end_parse", [
@@ -52,6 +66,12 @@ export class MarkupParseContext {
         }
         return result;
     }
+    /**
+     * Frees a #GMarkupParseContext.
+     *
+     * This function can't be called from inside one of the
+     * #GMarkupParser functions or while a subparser is pushed.
+     */
     free() {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_markup_parse_context_free", [
             {
@@ -60,6 +80,13 @@ export class MarkupParseContext {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Retrieves the name of the currently open element.
+     *
+     * If called from the start_element or end_element handlers this will
+     * give the element_name as passed to those functions. For the parent
+     * elements, see g_markup_parse_context_get_element_stack().
+     */
     getElement() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_markup_parse_context_get_element", [
             {
@@ -68,6 +95,19 @@ export class MarkupParseContext {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * Retrieves the element stack from the internal state of the parser.
+     *
+     * The returned #GSList is a list of strings where the first item is
+     * the currently open tag (as would be returned by
+     * g_markup_parse_context_get_element()) and the next item is its
+     * immediate parent.
+     *
+     * This function is intended to be used in the start_element and
+     * end_element handlers where g_markup_parse_context_get_element()
+     * would merely return the name of the element that is being
+     * processed.
+     */
     getElementStack() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_markup_parse_context_get_element_stack", [
             {
@@ -81,6 +121,14 @@ export class MarkupParseContext {
             borrowed: true,
         });
     }
+    /**
+     * Retrieves the current line number and the number of the character on
+     * that line. Intended for use in error messages; there are no strict
+     * semantics for what constitutes the "current" line number other than
+     * "the best number we could come up with for error messages."
+     * @param lineNumber - return location for a line number, or %NULL
+     * @param charNumber - return location for a char-on-line number, or %NULL
+     */
     getPosition(lineNumber, charNumber) {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_markup_parse_context_get_position", [
             {
@@ -105,6 +153,13 @@ export class MarkupParseContext {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Returns the user_data associated with @context.
+     *
+     * This will either be the user_data that was provided to
+     * g_markup_parse_context_new() or to the most recent call
+     * of g_markup_parse_context_push().
+     */
     getUserData() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_markup_parse_context_get_user_data", [
             {
@@ -113,6 +168,20 @@ export class MarkupParseContext {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Feed some data to the #GMarkupParseContext.
+     *
+     * The data need not be valid UTF-8; an error will be signaled if
+     * it's invalid. The data need not be an entire document; you can
+     * feed a document into the parser incrementally, via multiple calls
+     * to this function. Typically, as you receive data from a network
+     * connection or file, you feed each received chunk of data into this
+     * function, aborting the process if an error occurs. Once an error
+     * is reported, no further data may be fed to the #GMarkupParseContext;
+     * all errors are fatal.
+     * @param text - chunk of text to parse
+     * @param textLen - length of `text` in bytes
+     */
     parse(text, textLen) {
         const error = { value: null };
         const result = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_markup_parse_context_parse", [
@@ -145,6 +214,21 @@ export class MarkupParseContext {
         }
         return result;
     }
+    /**
+     * Completes the process of a temporary sub-parser redirection.
+     *
+     * This function exists to collect the user_data allocated by a
+     * matching call to g_markup_parse_context_push(). It must be called
+     * in the end_element handler corresponding to the start_element
+     * handler during which g_markup_parse_context_push() was called.
+     * You must not call this function from the error callback -- the
+     * `user_data` is provided directly to the callback in that case.
+     *
+     * This function is not intended to be directly called by users
+     * interested in invoking subparsers. Instead, it is intended to
+     * be used by the subparsers themselves to implement a higher-level
+     * interface.
+     */
     pop() {
         return call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_markup_parse_context_pop", [
             {
@@ -153,6 +237,124 @@ export class MarkupParseContext {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Temporarily redirects markup data to a sub-parser.
+     *
+     * This function may only be called from the start_element handler of
+     * a #GMarkupParser. It must be matched with a corresponding call to
+     * g_markup_parse_context_pop() in the matching end_element handler
+     * (except in the case that the parser aborts due to an error).
+     *
+     * All tags, text and other data between the matching tags is
+     * redirected to the subparser given by @parser. `user_data` is used
+     * as the user_data for that parser. `user_data` is also passed to the
+     * error callback in the event that an error occurs. This includes
+     * errors that occur in subparsers of the subparser.
+     *
+     * The end tag matching the start tag for which this call was made is
+     * handled by the previous parser (which is given its own user_data)
+     * which is why g_markup_parse_context_pop() is provided to allow "one
+     * last access" to the `user_data` provided to this function. In the
+     * case of error, the `user_data` provided here is passed directly to
+     * the error callback of the subparser and g_markup_parse_context_pop()
+     * should not be called. In either case, if `user_data` was allocated
+     * then it ought to be freed from both of these locations.
+     *
+     * This function is not intended to be directly called by users
+     * interested in invoking subparsers. Instead, it is intended to be
+     * used by the subparsers themselves to implement a higher-level
+     * interface.
+     *
+     * As an example, see the following implementation of a simple
+     * parser that counts the number of tags encountered.
+     *
+     * |[<!-- language="C" -->
+     * typedef struct
+     * {
+     * gint tag_count;
+     * } CounterData;
+     *
+     * static void
+     * counter_start_element (GMarkupParseContext  *context,
+     * const gchar          *element_name,
+     * const gchar         **attribute_names,
+     * const gchar         **attribute_values,
+     * gpointer              user_data,
+     * GError              **error)
+     * {
+     * CounterData *data = user_data;
+     *
+     * data->tag_count++;
+     * }
+     *
+     * static void
+     * counter_error (GMarkupParseContext *context,
+     * GError              *error,
+     * gpointer             user_data)
+     * {
+     * CounterData *data = user_data;
+     *
+     * g_slice_free (CounterData, data);
+     * }
+     *
+     * static GMarkupParser counter_subparser =
+     * {
+     * counter_start_element,
+     * NULL,
+     * NULL,
+     * NULL,
+     * counter_error
+     * };
+     * ]|
+     *
+     * In order to allow this parser to be easily used as a subparser, the
+     * following interface is provided:
+     *
+     * |[<!-- language="C" -->
+     * void
+     * start_counting (GMarkupParseContext *context)
+     * {
+     * CounterData *data = g_slice_new (CounterData);
+     *
+     * data->tag_count = 0;
+     * g_markup_parse_context_push (context, &counter_subparser, data);
+     * }
+     *
+     * gint
+     * end_counting (GMarkupParseContext *context)
+     * {
+     * CounterData *data = g_markup_parse_context_pop (context);
+     * int result;
+     *
+     * result = data->tag_count;
+     * g_slice_free (CounterData, data);
+     *
+     * return result;
+     * }
+     * ]|
+     *
+     * The subparser would then be used as follows:
+     *
+     * |[<!-- language="C" -->
+     * static void start_element (context, element_name, ...)
+     * {
+     * if (strcmp (element_name, "count-these") == 0)
+     * start_counting (context);
+     *
+     * // else, handle other tags...
+     * }
+     *
+     * static void end_element (context, element_name, ...)
+     * {
+     * if (strcmp (element_name, "count-these") == 0)
+     * g_print ("Counted %d tags\n", end_counting (context));
+     *
+     * // else, handle other tags...
+     * }
+     * ]|
+     * @param parser - a #GMarkupParser
+     * @param userData - user data to pass to #GMarkupParser functions
+     */
     push(parser, userData) {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_markup_parse_context_push", [
             {
@@ -170,6 +372,9 @@ export class MarkupParseContext {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Increases the reference count of @context.
+     */
     ref() {
         const ptr = call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_markup_parse_context_ref", [
             {
@@ -184,6 +389,10 @@ export class MarkupParseContext {
         });
         return getObject(ptr, MarkupParseContext);
     }
+    /**
+     * Decreases the reference count of @context.  When its reference count
+     * drops to 0, it is freed.
+     */
     unref() {
         call("libgobject-2.0.so.0,libglib-2.0.so.0", "g_markup_parse_context_unref", [
             {

package/dist/generated/glib/match-info.d.ts

@@ -1,22 +1,391 @@
 import { Ref } from "@gtkx/native";
 import { Regex } from "./regex.js";
+/**
+ * A GMatchInfo is an opaque struct used to return information about
+ * matches.
+ */
 export declare class MatchInfo {
     ptr: unknown;
     constructor();
     protected createPtr(_init: Record<string, unknown>): unknown;
+    /**
+     * Returns a new string containing the text in `string_to_expand` with
+     * references and escape sequences expanded. References refer to the last
+     * match done with `string` against `regex` and have the same syntax used by
+     * g_regex_replace().
+     *
+     * The `string_to_expand` must be UTF-8 encoded even if %G_REGEX_RAW was
+     * passed to g_regex_new().
+     *
+     * The backreferences are extracted from the string passed to the match
+     * function, so you cannot call this function after freeing the string.
+     *
+     * `match_info` may be %NULL in which case `string_to_expand` must not
+     * contain references. For instance "foo\n" does not refer to an actual
+     * pattern and '\n' merely will be replaced with \n character,
+     * while to expand "\0" (whole match) one needs the result of a match.
+     * Use g_regex_check_replacement() to find out whether `string_to_expand` contains references.
+     * @param stringToExpand - the string to expand
+     */
     expandReferences(stringToExpand: string): string | null;
+    /**
+     * Retrieves the text matching the @match_num'th capturing
+     * parentheses. 0 is the full text of the match, 1 is the first paren
+     * set, 2 the second, and so on.
+     *
+     * If `match_num` is a valid sub pattern but it didn't match anything
+     * (e.g. sub pattern 1, matching "b" against "(a)?b") then an empty
+     * string is returned.
+     *
+     * If the match was obtained using the DFA algorithm, that is using
+     * g_regex_match_all() or g_regex_match_all_full(), the retrieved
+     * string is not that of a set of parentheses but that of a matched
+     * substring. Substrings are matched in reverse order of length, so
+     * 0 is the longest match.
+     *
+     * The string is fetched from the string passed to the match function,
+     * so you cannot call this function after freeing the string.
+     * @param matchNum - number of the sub expression
+     */
     fetch(matchNum: number): string | null;
+    /**
+     * Bundles up pointers to each of the matching substrings from a match
+     * and stores them in an array of gchar pointers. The first element in
+     * the returned array is the match number 0, i.e. the entire matched
+     * text.
+     *
+     * If a sub pattern didn't match anything (e.g. sub pattern 1, matching
+     * "b" against "(a)?b") then an empty string is inserted.
+     *
+     * If the last match was obtained using the DFA algorithm, that is using
+     * g_regex_match_all() or g_regex_match_all_full(), the retrieved
+     * strings are not that matched by sets of parentheses but that of the
+     * matched substring. Substrings are matched in reverse order of length,
+     * so the first one is the longest match.
+     *
+     * The strings are fetched from the string passed to the match function,
+     * so you cannot call this function after freeing the string.
+     */
     fetchAll(): string[];
+    /**
+     * Retrieves the text matching the capturing parentheses named @name.
+     *
+     * If `name` is a valid sub pattern name but it didn't match anything
+     * (e.g. sub pattern `"X"`, matching `"b"` against `"(?P<X>a)?b"`)
+     * then an empty string is returned.
+     *
+     * The string is fetched from the string passed to the match function,
+     * so you cannot call this function after freeing the string.
+     * @param name - name of the subexpression
+     */
     fetchNamed(name: string): string | null;
+    /**
+     * Retrieves the position in bytes of the capturing parentheses named @name.
+     *
+     * If `name` is a valid sub pattern name but it didn't match anything
+     * (e.g. sub pattern `"X"`, matching `"b"` against `"(?P<X>a)?b"`)
+     * then `start_pos` and `end_pos` are set to -1 and %TRUE is returned.
+     *
+     * As `end_pos` is set to the byte after the final byte of the match (on success),
+     * the length of the match can be calculated as `end_pos - start_pos`.
+     * @param name - name of the subexpression
+     * @param startPos - pointer to location where to store
+     * @param endPos - pointer to location where to store
+     */
     fetchNamedPos(name: string, startPos?: Ref<number> | null, endPos?: Ref<number> | null): boolean;
+    /**
+     * Returns the start and end positions (in bytes) of a successfully matching
+     * capture parenthesis.
+     *
+     * Valid values for `match_num` are `0` for the full text of the match,
+     * `1` for the first paren set, `2` for the second, and so on.
+     *
+     * As `end_pos` is set to the byte after the final byte of the match (on success),
+     * the length of the match can be calculated as `end_pos - start_pos`.
+     *
+     * As a best practice, initialize `start_pos` and `end_pos` to identifiable
+     * values, such as `G_MAXINT`, so that you can test if
+     * `g_match_info_fetch_pos()` actually changed the value for a given
+     * capture parenthesis.
+     *
+     * The parameter `match_num` corresponds to a matched capture parenthesis. The
+     * actual value you use for `match_num` depends on the method used to generate
+     * @match_info. The following sections describe those methods.
+     *
+     * ## Methods Using Non-deterministic Finite Automata Matching
+     *
+     * The methods [method@GLib.Regex.match] and [method@GLib.Regex.match_full]
+     * return a [struct@GLib.MatchInfo] using traditional (greedy) pattern
+     * matching, also known as
+     * [Non-deterministic Finite Automaton](https://en.wikipedia.org/wiki/Nondeterministic_finite_automaton)
+     * (NFA) matching. You pass the returned `GMatchInfo` from these methods to
+     * `g_match_info_fetch_pos()` to determine the start and end positions
+     * of capture parentheses. The values for `match_num` correspond to the capture
+     * parentheses in order, with `0` corresponding to the entire matched string.
+     *
+     * `match_num` can refer to a capture parenthesis with no match. For example,
+     * the string `b` matches against the pattern `(a)?b`, but the capture
+     * parenthesis `(a)` has no match. In this case, `g_match_info_fetch_pos()`
+     * returns true and sets `start_pos` and `end_pos` to `-1` when called with
+     * `match_num` as `1` (for `(a)`).
+     *
+     * For an expanded example, a regex pattern is `(a)?(.*?)the (.*)`,
+     * and a candidate string is `glib regexes are the best`. In this scenario
+     * there are four capture parentheses numbered 0–3: an implicit one
+     * for the entire string, and three explicitly declared in the regex pattern.
+     *
+     * Given this example, the following table describes the return values
+     * from `g_match_info_fetch_pos()` for various values of @match_num.
+     *
+     * `match_num` | Contents | Return value | Returned `start_pos` | Returned `end_pos`
+     * ----------- | -------- | ------------ | -------------------- | ------------------
+     * 0 | Matches entire string | True | 0 | 25
+     * 1 | Does not match first character | True | -1 | -1
+     * 2 | All text before `the ` | True | 0 | 17
+     * 3 | All text after `the ` | True | 21 | 25
+     * 4 | Capture paren out of range | False | Unchanged | Unchanged
+     *
+     * The following code sample and output implements this example.
+     *
+     * ``` { .c }
+     * #include <glib.h>
+     *
+     * int
+     * main (int argc, char *argv[])
+     * {
+     * g_autoptr(GError) local_error = NULL;
+     * const char *regex_pattern = "(a)?(.*?)the (.*)";
+     * const char *test_string = "glib regexes are the best";
+     * g_autoptr(GRegex) regex = NULL;
+     *
+     * regex = g_regex_new (regex_pattern,
+     * G_REGEX_DEFAULT,
+     * G_REGEX_MATCH_DEFAULT,
+     * &local_error);
+     * if (regex == NULL)
+     * {
+     * g_printerr ("Error creating regex: %s\n", local_error->message);
+     * return 1;
+     * }
+     *
+     * g_autoptr(GMatchInfo) match_info = NULL;
+     * g_regex_match (regex, test_string, G_REGEX_MATCH_DEFAULT, &match_info);
+     *
+     * int n_matched_strings = g_match_info_get_match_count (match_info);
+     *
+     * // Print header line
+     * g_print ("match_num Contents                  Return value returned start_pos returned end_pos\n");
+     *
+     * // Iterate over each capture paren, including one that is out of range as a demonstration.
+     * for (int match_num = 0; match_num <= n_matched_strings; match_num++)
+     * {
+     * gboolean found_match;
+     * g_autofree char *paren_string = NULL;
+     * int start_pos = G_MAXINT;
+     * int end_pos = G_MAXINT;
+     *
+     * found_match = g_match_info_fetch_pos (match_info,
+     * match_num,
+     * &start_pos,
+     * &end_pos);
+     *
+     * // If no match, display N/A as the found string.
+     * if (start_pos == G_MAXINT || start_pos == -1)
+     * paren_string = g_strdup ("N/A");
+     * else
+     * paren_string = g_strndup (test_string + start_pos, end_pos - start_pos);
+     *
+     * g_print ("%-9d %-25s %-12d %-18d %d\n", match_num, paren_string, found_match, start_pos, end_pos);
+     * }
+     *
+     * return 0;
+     * }
+     * ```
+     *
+     * ```
+     * match_num Contents                  Return value returned start_pos returned end_pos
+     * 0         glib regexes are the best 1            0                  25
+     * 1         N/A                       1            -1                 -1
+     * 2         glib regexes are          1            0                  17
+     * 3         best                      1            21                 25
+     * 4         N/A                       0            2147483647         2147483647
+     * ```
+     * ## Methods Using Deterministic Finite Automata Matching
+     *
+     * The methods [method@GLib.Regex.match_all] and
+     * [method@GLib.Regex.match_all_full]
+     * return a `GMatchInfo` using
+     * [Deterministic Finite Automaton](https://en.wikipedia.org/wiki/Deterministic_finite_automaton)
+     * (DFA) pattern matching. This algorithm detects overlapping matches. You pass
+     * the returned `GMatchInfo` from these methods to `g_match_info_fetch_pos()`
+     * to determine the start and end positions of each overlapping match. Use the
+     * method [method@GLib.MatchInfo.get_match_count] to determine the number
+     * of overlapping matches.
+     *
+     * For example, a regex pattern is `<.*>`, and a candidate string is
+     * `<a> <b> <c>`. In this scenario there are three implicit capture
+     * parentheses: one for the entire string, one for `<a> <b>`, and one for `<a>`.
+     *
+     * Given this example, the following table describes the return values from
+     * `g_match_info_fetch_pos()` for various values of @match_num.
+     *
+     * `match_num` | Contents | Return value | Returned `start_pos` | Returned `end_pos`
+     * ----------- | -------- | ------------ | -------------------- | ------------------
+     * 0 | Matches entire string | True | 0 | 11
+     * 1 | Matches `<a> <b>` | True | 0 | 7
+     * 2 | Matches `<a>` | True | 0 | 3
+     * 3 | Capture paren out of range | False | Unchanged | Unchanged
+     *
+     * The following code sample and output implements this example.
+     *
+     * ``` { .c }
+     * #include <glib.h>
+     *
+     * int
+     * main (int argc, char *argv[])
+     * {
+     * g_autoptr(GError) local_error = NULL;
+     * const char *regex_pattern = "<.*>";
+     * const char *test_string = "<a> <b> <c>";
+     * g_autoptr(GRegex) regex = NULL;
+     *
+     * regex = g_regex_new (regex_pattern,
+     * G_REGEX_DEFAULT,
+     * G_REGEX_MATCH_DEFAULT,
+     * &local_error);
+     * if (regex == NULL)
+     * {
+     * g_printerr ("Error creating regex: %s\n", local_error->message);
+     * return -1;
+     * }
+     *
+     * g_autoptr(GMatchInfo) match_info = NULL;
+     * g_regex_match_all (regex, test_string, G_REGEX_MATCH_DEFAULT, &match_info);
+     *
+     * int n_matched_strings = g_match_info_get_match_count (match_info);
+     *
+     * // Print header line
+     * g_print ("match_num Contents                  Return value returned start_pos returned end_pos\n");
+     *
+     * // Iterate over each capture paren, including one that is out of range as a demonstration.
+     * for (int match_num = 0; match_num <= n_matched_strings; match_num++)
+     * {
+     * gboolean found_match;
+     * g_autofree char *paren_string = NULL;
+     * int start_pos = G_MAXINT;
+     * int end_pos = G_MAXINT;
+     *
+     * found_match = g_match_info_fetch_pos (match_info, match_num, &start_pos, &end_pos);
+     *
+     * // If no match, display N/A as the found string.
+     * if (start_pos == G_MAXINT || start_pos == -1)
+     * paren_string = g_strdup ("N/A");
+     * else
+     * paren_string = g_strndup (test_string + start_pos, end_pos - start_pos);
+     *
+     * g_print ("%-9d %-25s %-12d %-18d %d\n", match_num, paren_string, found_match, start_pos, end_pos);
+     * }
+     *
+     * return 0;
+     * }
+     * ```
+     *
+     * ```
+     * match_num Contents                  Return value returned start_pos returned end_pos
+     * 0         <a> <b> <c>               1            0                  11
+     * 1         <a> <b>                   1            0                  7
+     * 2         <a>                       1            0                  3
+     * 3         N/A                       0            2147483647         2147483647
+     * ```
+     * @param matchNum - number of the capture parenthesis
+     * @param startPos - pointer to location where to store
+     * @param endPos - pointer to location where to store
+     */
     fetchPos(matchNum: number, startPos?: Ref<number> | null, endPos?: Ref<number> | null): boolean;
+    /**
+     * If `match_info` is not %NULL, calls g_match_info_unref(); otherwise does
+     * nothing.
+     */
     free(): void;
+    /**
+     * Retrieves the number of matched substrings (including substring 0,
+     * that is the whole matched text), so 1 is returned if the pattern
+     * has no substrings in it and 0 is returned if the match failed.
+     *
+     * If the last match was obtained using the DFA algorithm, that is
+     * using g_regex_match_all() or g_regex_match_all_full(), the retrieved
+     * count is not that of the number of capturing parentheses but that of
+     * the number of matched substrings.
+     */
     getMatchCount(): number;
+    /**
+     * Returns #GRegex object used in @match_info. It belongs to Glib
+     * and must not be freed. Use g_regex_ref() if you need to keep it
+     * after you free `match_info` object.
+     */
     getRegex(): Regex;
+    /**
+     * Returns the string searched with @match_info. This is the
+     * string passed to g_regex_match() or g_regex_replace() so
+     * you may not free it before calling this function.
+     */
     getString(): string;
+    /**
+     * Usually if the string passed to g_regex_match*() matches as far as
+     * it goes, but is too short to match the entire pattern, %FALSE is
+     * returned. There are circumstances where it might be helpful to
+     * distinguish this case from other cases in which there is no match.
+     *
+     * Consider, for example, an application where a human is required to
+     * type in data for a field with specific formatting requirements. An
+     * example might be a date in the form ddmmmyy, defined by the pattern
+     * "^\d?\d(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\d\d$".
+     * If the application sees the user’s keystrokes one by one, and can
+     * check that what has been typed so far is potentially valid, it is
+     * able to raise an error as soon as a mistake is made.
+     *
+     * GRegex supports the concept of partial matching by means of the
+     * %G_REGEX_MATCH_PARTIAL_SOFT and %G_REGEX_MATCH_PARTIAL_HARD flags.
+     * When they are used, the return code for
+     * g_regex_match() or g_regex_match_full() is, as usual, %TRUE
+     * for a complete match, %FALSE otherwise. But, when these functions
+     * return %FALSE, you can check if the match was partial calling
+     * g_match_info_is_partial_match().
+     *
+     * The difference between %G_REGEX_MATCH_PARTIAL_SOFT and
+     * %G_REGEX_MATCH_PARTIAL_HARD is that when a partial match is encountered
+     * with %G_REGEX_MATCH_PARTIAL_SOFT, matching continues to search for a
+     * possible complete match, while with %G_REGEX_MATCH_PARTIAL_HARD matching
+     * stops at the partial match.
+     * When both %G_REGEX_MATCH_PARTIAL_SOFT and %G_REGEX_MATCH_PARTIAL_HARD
+     * are set, the latter takes precedence.
+     *
+     * There were formerly some restrictions on the pattern for partial matching.
+     * The restrictions no longer apply.
+     *
+     * See pcrepartial(3) for more information on partial matching.
+     */
     isPartialMatch(): boolean;
+    /**
+     * Returns whether the previous match operation succeeded.
+     */
     matches(): boolean;
+    /**
+     * Scans for the next match using the same parameters of the previous
+     * call to g_regex_match_full() or g_regex_match() that returned
+     * @match_info.
+     *
+     * The match is done on the string passed to the match function, so you
+     * cannot free it before calling this function.
+     */
     next(): boolean;
+    /**
+     * Increases reference count of `match_info` by 1.
+     */
     ref(): MatchInfo;
+    /**
+     * Decreases reference count of `match_info` by 1. When reference count drops
+     * to zero, it frees all the memory associated with the match_info structure.
+     */
     unref(): void;
 }