@gtkx/ffi 0.1.45 → 0.1.47

package/dist/generated/gio/cancellable.js

@@ -2,10 +2,27 @@ import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GCancellable` allows operations to be cancelled.
+ *
+ * `GCancellable` is a thread-safe operation cancellation stack used
+ * throughout GIO to allow for cancellation of synchronous and
+ * asynchronous operations.
+ */
 const SIGNAL_META = {
     cancelled: { params: [], returnType: { type: "undefined" } },
 };
 export class Cancellable extends GObject.GObject {
+    /**
+     * Creates a new #GCancellable object.
+     *
+     * Applications that want to start one or more operations
+     * that should be cancellable should create a #GCancellable
+     * and pass it to the operations.
+     *
+     * One #GCancellable can be used in multiple consecutive
+     * operations or in multiple concurrent operations.
+     */
     constructor(...args) {
         super(...args);
     }
@@ -15,6 +32,9 @@ export class Cancellable extends GObject.GObject {
             borrowed: false,
         });
     }
+    /**
+     * Gets the top cancellable from the stack.
+     */
     static getCurrent() {
         const ptr = call("libgio-2.0.so.0", "g_cancellable_get_current", [], {
             type: "gobject",
@@ -22,6 +42,27 @@ export class Cancellable extends GObject.GObject {
         });
         return getObject(ptr, Cancellable);
     }
+    /**
+     * Will set `cancellable` to cancelled, and will emit the
+     * #GCancellable::cancelled signal. (However, see the warning about
+     * race conditions in the documentation for that signal if you are
+     * planning to connect to it.)
+     *
+     * This function is thread-safe. In other words, you can safely call
+     * it from a thread other than the one running the operation that was
+     * passed the @cancellable.
+     *
+     * If `cancellable` is %NULL, this function returns immediately for convenience.
+     *
+     * The convention within GIO is that cancelling an asynchronous
+     * operation causes it to complete asynchronously. That is, if you
+     * cancel the operation from the same thread in which it is running,
+     * then the operation's #GAsyncReadyCallback will not be invoked until
+     * the application returns to the main loop.
+     *
+     * It is safe (although useless, since it will be a no-op) to call
+     * this function from a [signal@Gio.Cancellable::cancelled] signal handler.
+     */
     cancel() {
         call("libgio-2.0.so.0", "g_cancellable_cancel", [
             {
@@ -30,6 +71,46 @@ export class Cancellable extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Convenience function to connect to the #GCancellable::cancelled
+     * signal. Also handles the race condition that may happen
+     * if the cancellable is cancelled right before connecting.
+     *
+     * `callback` is called exactly once each time `cancellable` is cancelled,
+     * either directly at the time of the connect if `cancellable` is already
+     * cancelled, or when `cancellable` is cancelled in some thread.
+     * In case the cancellable is reset via [method@Gio.Cancellable.reset]
+     * then the callback can be called again if the `cancellable` is cancelled and
+     * if it had not been previously cancelled at the time
+     * [method@Gio.Cancellable.connect] was called (e.g. if the connection actually
+     * took place, returning a non-zero value).
+     *
+     * `data_destroy_func` will be called when the handler is
+     * disconnected, or immediately if the cancellable is already
+     * cancelled.
+     *
+     * See #GCancellable::cancelled for details on how to use this.
+     *
+     * Since GLib 2.40, the lock protecting `cancellable` is not held when
+     * `callback` is invoked. This lifts a restriction in place for
+     * earlier GLib versions which now makes it easier to write cleanup
+     * code that unconditionally invokes e.g. [method@Gio.Cancellable.cancel].
+     * Note that since 2.82 GLib still holds a lock during the callback but it’s
+     * designed in a way that most of the [class@Gio.Cancellable] methods can be
+     * called, including [method@Gio.Cancellable.cancel] or
+     * [method@GObject.Object.unref].
+     *
+     * There are still some methods that will deadlock (by design) when
+     * called from the [signal@Gio.Cancellable::cancelled] callbacks:
+     * - [method@Gio.Cancellable.connect]
+     * - [method@Gio.Cancellable.disconnect]
+     * - [method@Gio.Cancellable.reset]
+     * - [method@Gio.Cancellable.make_pollfd]
+     * - [method@Gio.Cancellable.release_fd]
+     * @param callback - The #GCallback to connect.
+     * @param data - Data to pass to @callback.
+     * @param dataDestroyFunc - Free function for `data` or %NULL.
+     */
     connectCallback(callback, data, dataDestroyFunc) {
         return call("libgio-2.0.so.0", "g_cancellable_connect", [
             {
@@ -52,6 +133,23 @@ export class Cancellable extends GObject.GObject {
             },
         ], { type: "int", size: 64, unsigned: true });
     }
+    /**
+     * Disconnects a handler from a cancellable instance similar to
+     * g_signal_handler_disconnect().  Additionally, in the event that a
+     * signal handler is currently running, this call will block until the
+     * handler has finished.  Calling this function from a
+     * #GCancellable::cancelled signal handler will therefore result in a
+     * deadlock.
+     *
+     * This avoids a race condition where a thread cancels at the
+     * same time as the cancellable operation is finished and the
+     * signal handler is removed. See #GCancellable::cancelled for
+     * details on how to use this.
+     *
+     * If `cancellable` is %NULL or `handler_id` is `0` this function does
+     * nothing.
+     * @param handlerId - Handler id of the handler to be disconnected, or `0`.
+     */
     disconnect(handlerId) {
         call("libgio-2.0.so.0", "g_cancellable_disconnect", [
             {
@@ -64,6 +162,21 @@ export class Cancellable extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Gets the file descriptor for a cancellable job. This can be used to
+     * implement cancellable operations on Unix systems. The returned fd will
+     * turn readable when `cancellable` is cancelled.
+     *
+     * You are not supposed to read from the fd yourself, just check for
+     * readable status. Reading to unset the readable status is done
+     * with g_cancellable_reset().
+     *
+     * After a successful return from this function, you should use
+     * g_cancellable_release_fd() to free up resources allocated for
+     * the returned file descriptor.
+     *
+     * See also g_cancellable_make_pollfd().
+     */
     getFd() {
         return call("libgio-2.0.so.0", "g_cancellable_get_fd", [
             {
@@ -72,6 +185,9 @@ export class Cancellable extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Checks if a cancellable job has been cancelled.
+     */
     isCancelled() {
         return call("libgio-2.0.so.0", "g_cancellable_is_cancelled", [
             {
@@ -80,6 +196,32 @@ export class Cancellable extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Creates a #GPollFD corresponding to @cancellable; this can be passed
+     * to g_poll() and used to poll for cancellation. This is useful both
+     * for unix systems without a native poll and for portability to
+     * windows.
+     *
+     * When this function returns %TRUE, you should use
+     * g_cancellable_release_fd() to free up resources allocated for the
+     * @pollfd. After a %FALSE return, do not call g_cancellable_release_fd().
+     *
+     * If this function returns %FALSE, either no `cancellable` was given or
+     * resource limits prevent this function from allocating the necessary
+     * structures for polling. (On Linux, you will likely have reached
+     * the maximum number of file descriptors.) The suggested way to handle
+     * these cases is to ignore the @cancellable.
+     *
+     * You are not supposed to read from the fd yourself, just check for
+     * readable status. Reading to unset the readable status is done
+     * with g_cancellable_reset().
+     *
+     * Note that in the event that a [signal@Gio.Cancellable::cancelled] signal handler is
+     * currently running, this call will block until the handler has finished.
+     * Calling this function from a signal handler will therefore result in a
+     * deadlock.
+     * @param pollfd - a pointer to a #GPollFD
+     */
     makePollfd(pollfd) {
         return call("libgio-2.0.so.0", "g_cancellable_make_pollfd", [
             {
@@ -97,6 +239,9 @@ export class Cancellable extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Pops `cancellable` off the cancellable stack (verifying that `cancellable` is on the top of the stack).
+     */
     popCurrent() {
         call("libgio-2.0.so.0", "g_cancellable_pop_current", [
             {
@@ -105,6 +250,16 @@ export class Cancellable extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Pushes `cancellable` onto the cancellable stack. The current
+     * cancellable can then be received using g_cancellable_get_current().
+     *
+     * This is useful when implementing cancellable operations in
+     * code that does not allow you to pass down the cancellable object.
+     *
+     * This is typically called automatically by e.g. #GFile operations,
+     * so you rarely have to call this yourself.
+     */
     pushCurrent() {
         call("libgio-2.0.so.0", "g_cancellable_push_current", [
             {
@@ -113,6 +268,22 @@ export class Cancellable extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Releases a resources previously allocated by g_cancellable_get_fd()
+     * or g_cancellable_make_pollfd().
+     *
+     * For compatibility reasons with older releases, calling this function
+     * is not strictly required, the resources will be automatically freed
+     * when the `cancellable` is finalized. However, the `cancellable` will
+     * block scarce file descriptors until it is finalized if this function
+     * is not called. This can cause the application to run out of file
+     * descriptors when many #GCancellables are used at the same time.
+     *
+     * Note that in the event that a [signal@Gio.Cancellable::cancelled] signal handler is
+     * currently running, this call will block until the handler has finished.
+     * Calling this function from a signal handler will therefore result in a
+     * deadlock.
+     */
     releaseFd() {
         call("libgio-2.0.so.0", "g_cancellable_release_fd", [
             {
@@ -121,6 +292,24 @@ export class Cancellable extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Resets `cancellable` to its uncancelled state.
+     *
+     * If cancellable is currently in use by any cancellable operation
+     * then the behavior of this function is undefined.
+     *
+     * Note that it is generally not a good idea to reuse an existing
+     * cancellable for more operations after it has been cancelled once,
+     * as this function might tempt you to do. The recommended practice
+     * is to drop the reference to a cancellable after cancelling it,
+     * and let it die with the outstanding async operations. You should
+     * create a fresh cancellable for further async operations.
+     *
+     * In the event that a [signal@Gio.Cancellable::cancelled] signal handler is currently
+     * running, this call will block until the handler has finished.
+     * Calling this function from a signal handler will therefore result in a
+     * deadlock.
+     */
     reset() {
         call("libgio-2.0.so.0", "g_cancellable_reset", [
             {
@@ -129,6 +318,10 @@ export class Cancellable extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * If the `cancellable` is cancelled, sets the error to notify
+     * that the operation was cancelled.
+     */
     setErrorIfCancelled() {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_cancellable_set_error_if_cancelled", [
@@ -153,6 +346,17 @@ export class Cancellable extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Creates a source that triggers if `cancellable` is cancelled and
+     * calls its callback of type #GCancellableSourceFunc. This is
+     * primarily useful for attaching to another (non-cancellable) source
+     * with g_source_add_child_source() to add cancellability to it.
+     *
+     * For convenience, you can call this with a %NULL #GCancellable,
+     * in which case the source will never trigger.
+     *
+     * The new #GSource will hold a reference to the #GCancellable.
+     */
     sourceNew() {
         const ptr = call("libgio-2.0.so.0", "g_cancellable_source_new", [
             {

package/dist/generated/gio/charset-converter.d.ts

@@ -3,16 +3,176 @@ import { ConverterFlags, ConverterResult } from "./enums.js";
 import { Cancellable } from "./cancellable.js";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GCharsetConverter` is an implementation of [iface@Gio.Converter] based on
+ * [struct@GLib.IConv].
+ */
 export declare class CharsetConverter extends GObject.GObject {
+    /**
+     * Creates a new #GCharsetConverter.
+     * @param toCharset - destination charset
+     * @param fromCharset - source charset
+     */
     constructor(toCharset: string, fromCharset: string);
     constructor(...args: unknown[]);
     protected createPtr(args: unknown[]): unknown;
+    /**
+     * Gets the number of fallbacks that `converter` has applied so far.
+     */
     getNumFallbacks(): number;
+    /**
+     * Gets the #GCharsetConverter:use-fallback property.
+     */
     getUseFallback(): boolean;
+    /**
+     * Sets the #GCharsetConverter:use-fallback property.
+     * @param useFallback - %TRUE to use fallbacks
+     */
     setUseFallback(useFallback: boolean): void;
+    /**
+     * This is the main operation used when converting data. It is to be called
+     * multiple times in a loop, and each time it will do some work, i.e.
+     * producing some output (in @outbuf) or consuming some input (from @inbuf) or
+     * both. If its not possible to do any work an error is returned.
+     *
+     * Note that a single call may not consume all input (or any input at all).
+     * Also a call may produce output even if given no input, due to state stored
+     * in the converter producing output.
+     *
+     * If any data was either produced or consumed, and then an error happens, then
+     * only the successful conversion is reported and the error is returned on the
+     * next call.
+     *
+     * A full conversion loop involves calling this method repeatedly, each time
+     * giving it new input and space output space. When there is no more input
+     * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
+     * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
+     * each time until all data is consumed and all output is produced, then
+     * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
+     * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
+     * in a decompression converter where the end of data is detectable from the
+     * data (and there might even be other data after the end of the compressed data).
+     *
+     * When some data has successfully been converted `bytes_read` and is set to
+     * the number of bytes read from @inbuf, and `bytes_written` is set to indicate
+     * how many bytes was written to @outbuf. If there are more data to output
+     * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
+     * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
+     * then %G_CONVERTER_FINISHED is returned.
+     *
+     * On error %G_CONVERTER_ERROR is returned and `error` is set accordingly.
+     * Some errors need special handling:
+     *
+     * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
+     * to write the resulting converted data, the application should
+     * call the function again with a larger `outbuf` to continue.
+     *
+     * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
+     * input to fully determine what the conversion should produce,
+     * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
+     * example with an incomplete multibyte sequence when converting text,
+     * or when a regexp matches up to the end of the input (and may match
+     * further input). It may also happen when `inbuf_size` is zero and
+     * there is no more data to produce.
+     *
+     * When this happens the application should read more input and then
+     * call the function again. If further input shows that there is no
+     * more data call the function again with the same data but with
+     * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
+     * to finish as e.g. in the regexp match case (or, to fail again with
+     * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
+     * input is actually partial).
+     *
+     * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
+     * converter object is in an invalid state where its not allowed
+     * to call g_converter_convert() anymore. At this time you can only
+     * free the object or call g_converter_reset() to reset it to the
+     * initial state.
+     *
+     * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
+     * to try to write out all internal state to the output. The application
+     * has to call the function multiple times with the flag set, and when
+     * the available input has been consumed and all internal state has
+     * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
+     * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
+     * This is somewhat similar to what happens at the end of the input stream,
+     * but done in the middle of the data.
+     *
+     * This has different meanings for different conversions. For instance
+     * in a compression converter it would mean that we flush all the
+     * compression state into output such that if you uncompress the
+     * compressed data you get back all the input data. Doing this may
+     * make the final file larger due to padding though. Another example
+     * is a regexp conversion, where if you at the end of the flushed data
+     * have a match, but there is also a potential longer match. In the
+     * non-flushed case we would ask for more input, but when flushing we
+     * treat this as the end of input and do the match.
+     *
+     * Flushing is not always possible (like if a charset converter flushes
+     * at a partial multibyte sequence). Converters are supposed to try
+     * to produce as much output as possible and then return an error
+     * (typically %G_IO_ERROR_PARTIAL_INPUT).
+     * @param inbuf - the buffer
+     * @param inbufSize - the number of bytes in @inbuf
+     * @param outbuf - a
+     * @param outbufSize - the number of bytes in @outbuf, must be at least one
+     * @param flags - a #GConverterFlags controlling the conversion details
+     * @param bytesRead - will be set to the number of bytes read
+     * @param bytesWritten - will be set to the number of bytes
+     */
     convert(inbuf: number[], inbufSize: number, outbuf: number[], outbufSize: number, flags: ConverterFlags, bytesRead: Ref<number>, bytesWritten: Ref<number>): ConverterResult;
+    /**
+     * Applies `converter` to the data in @bytes.
+     * @param bytes - the data to convert
+     */
     convertBytes(bytes: GLib.Bytes): GLib.Bytes;
+    /**
+     * Resets all internal state in the converter, making it behave
+     * as if it was just created. If the converter has any internal
+     * state that would produce output then that output is lost.
+     */
     reset(): void;
+    /**
+     * Initializes the object implementing the interface.
+     *
+     * This method is intended for language bindings. If writing in C,
+     * g_initable_new() should typically be used instead.
+     *
+     * The object must be initialized before any real use after initial
+     * construction, either with this function or g_async_initable_init_async().
+     *
+     * Implementations may also support cancellation. If `cancellable` is not %NULL,
+     * then initialization can be cancelled by triggering the cancellable object
+     * from another thread. If the operation was cancelled, the error
+     * %G_IO_ERROR_CANCELLED will be returned. If `cancellable` is not %NULL and
+     * the object doesn't support cancellable initialization the error
+     * %G_IO_ERROR_NOT_SUPPORTED will be returned.
+     *
+     * If the object is not initialized, or initialization returns with an
+     * error, then all operations on the object except g_object_ref() and
+     * g_object_unref() are considered to be invalid, and have undefined
+     * behaviour. See the [description][iface@Gio.Initable#description] for more details.
+     *
+     * Callers should not assume that a class which implements #GInitable can be
+     * initialized multiple times, unless the class explicitly documents itself as
+     * supporting this. Generally, a class’ implementation of init() can assume
+     * (and assert) that it will only be called once. Previously, this documentation
+     * recommended all #GInitable implementations should be idempotent; that
+     * recommendation was relaxed in GLib 2.54.
+     *
+     * If a class explicitly supports being initialized multiple times, it is
+     * recommended that the method is idempotent: multiple calls with the same
+     * arguments should return the same results. Only the first call initializes
+     * the object; further calls return the result of the first call.
+     *
+     * One reason why a class might need to support idempotent initialization is if
+     * it is designed to be used via the singleton pattern, with a
+     * #GObjectClass.constructor that sometimes returns an existing instance.
+     * In this pattern, a caller would expect to be able to call g_initable_init()
+     * on the result of g_object_new(), regardless of whether it is in fact a new
+     * instance.
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     init(cancellable?: Cancellable | null): boolean;
     connect(signal: "notify", handler: (self: CharsetConverter, pspec: GObject.ParamSpec) => void, after?: boolean): number;
     connect(signal: string, handler: (...args: any[]) => any, after?: boolean): number;

package/dist/generated/gio/charset-converter.js

@@ -2,6 +2,10 @@ import { call } from "@gtkx/native";
 import { NativeError, getObject } from "@gtkx/ffi";
 import * as GLib from "../glib/index.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GCharsetConverter` is an implementation of [iface@Gio.Converter] based on
+ * [struct@GLib.IConv].
+ */
 export class CharsetConverter extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -19,6 +23,9 @@ export class CharsetConverter extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Gets the number of fallbacks that `converter` has applied so far.
+     */
     getNumFallbacks() {
         return call("libgio-2.0.so.0", "g_charset_converter_get_num_fallbacks", [
             {
@@ -27,6 +34,9 @@ export class CharsetConverter extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: true });
     }
+    /**
+     * Gets the #GCharsetConverter:use-fallback property.
+     */
     getUseFallback() {
         return call("libgio-2.0.so.0", "g_charset_converter_get_use_fallback", [
             {
@@ -35,6 +45,10 @@ export class CharsetConverter extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * Sets the #GCharsetConverter:use-fallback property.
+     * @param useFallback - %TRUE to use fallbacks
+     */
     setUseFallback(useFallback) {
         call("libgio-2.0.so.0", "g_charset_converter_set_use_fallback", [
             {
@@ -47,6 +61,97 @@ export class CharsetConverter extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * This is the main operation used when converting data. It is to be called
+     * multiple times in a loop, and each time it will do some work, i.e.
+     * producing some output (in @outbuf) or consuming some input (from @inbuf) or
+     * both. If its not possible to do any work an error is returned.
+     *
+     * Note that a single call may not consume all input (or any input at all).
+     * Also a call may produce output even if given no input, due to state stored
+     * in the converter producing output.
+     *
+     * If any data was either produced or consumed, and then an error happens, then
+     * only the successful conversion is reported and the error is returned on the
+     * next call.
+     *
+     * A full conversion loop involves calling this method repeatedly, each time
+     * giving it new input and space output space. When there is no more input
+     * data after the data in @inbuf, the flag %G_CONVERTER_INPUT_AT_END must be set.
+     * The loop will be (unless some error happens) returning %G_CONVERTER_CONVERTED
+     * each time until all data is consumed and all output is produced, then
+     * %G_CONVERTER_FINISHED is returned instead. Note, that %G_CONVERTER_FINISHED
+     * may be returned even if %G_CONVERTER_INPUT_AT_END is not set, for instance
+     * in a decompression converter where the end of data is detectable from the
+     * data (and there might even be other data after the end of the compressed data).
+     *
+     * When some data has successfully been converted `bytes_read` and is set to
+     * the number of bytes read from @inbuf, and `bytes_written` is set to indicate
+     * how many bytes was written to @outbuf. If there are more data to output
+     * or consume (i.e. unless the %G_CONVERTER_INPUT_AT_END is specified) then
+     * %G_CONVERTER_CONVERTED is returned, and if no more data is to be output
+     * then %G_CONVERTER_FINISHED is returned.
+     *
+     * On error %G_CONVERTER_ERROR is returned and `error` is set accordingly.
+     * Some errors need special handling:
+     *
+     * %G_IO_ERROR_NO_SPACE is returned if there is not enough space
+     * to write the resulting converted data, the application should
+     * call the function again with a larger `outbuf` to continue.
+     *
+     * %G_IO_ERROR_PARTIAL_INPUT is returned if there is not enough
+     * input to fully determine what the conversion should produce,
+     * and the %G_CONVERTER_INPUT_AT_END flag is not set. This happens for
+     * example with an incomplete multibyte sequence when converting text,
+     * or when a regexp matches up to the end of the input (and may match
+     * further input). It may also happen when `inbuf_size` is zero and
+     * there is no more data to produce.
+     *
+     * When this happens the application should read more input and then
+     * call the function again. If further input shows that there is no
+     * more data call the function again with the same data but with
+     * the %G_CONVERTER_INPUT_AT_END flag set. This may cause the conversion
+     * to finish as e.g. in the regexp match case (or, to fail again with
+     * %G_IO_ERROR_PARTIAL_INPUT in e.g. a charset conversion where the
+     * input is actually partial).
+     *
+     * After g_converter_convert() has returned %G_CONVERTER_FINISHED the
+     * converter object is in an invalid state where its not allowed
+     * to call g_converter_convert() anymore. At this time you can only
+     * free the object or call g_converter_reset() to reset it to the
+     * initial state.
+     *
+     * If the flag %G_CONVERTER_FLUSH is set then conversion is modified
+     * to try to write out all internal state to the output. The application
+     * has to call the function multiple times with the flag set, and when
+     * the available input has been consumed and all internal state has
+     * been produced then %G_CONVERTER_FLUSHED (or %G_CONVERTER_FINISHED if
+     * really at the end) is returned instead of %G_CONVERTER_CONVERTED.
+     * This is somewhat similar to what happens at the end of the input stream,
+     * but done in the middle of the data.
+     *
+     * This has different meanings for different conversions. For instance
+     * in a compression converter it would mean that we flush all the
+     * compression state into output such that if you uncompress the
+     * compressed data you get back all the input data. Doing this may
+     * make the final file larger due to padding though. Another example
+     * is a regexp conversion, where if you at the end of the flushed data
+     * have a match, but there is also a potential longer match. In the
+     * non-flushed case we would ask for more input, but when flushing we
+     * treat this as the end of input and do the match.
+     *
+     * Flushing is not always possible (like if a charset converter flushes
+     * at a partial multibyte sequence). Converters are supposed to try
+     * to produce as much output as possible and then return an error
+     * (typically %G_IO_ERROR_PARTIAL_INPUT).
+     * @param inbuf - the buffer
+     * @param inbufSize - the number of bytes in @inbuf
+     * @param outbuf - a
+     * @param outbufSize - the number of bytes in @outbuf, must be at least one
+     * @param flags - a #GConverterFlags controlling the conversion details
+     * @param bytesRead - will be set to the number of bytes read
+     * @param bytesWritten - will be set to the number of bytes
+     */
     convert(inbuf, inbufSize, outbuf, outbufSize, flags, bytesRead, bytesWritten) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_converter_convert", [
@@ -111,6 +216,10 @@ export class CharsetConverter extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Applies `converter` to the data in @bytes.
+     * @param bytes - the data to convert
+     */
     convertBytes(bytes) {
         const error = { value: null };
         const ptr = call("libgio-2.0.so.0", "g_converter_convert_bytes", [
@@ -149,6 +258,11 @@ export class CharsetConverter extends GObject.GObject {
         }
         return getObject(ptr, GLib.Bytes);
     }
+    /**
+     * Resets all internal state in the converter, making it behave
+     * as if it was just created. If the converter has any internal
+     * state that would produce output then that output is lost.
+     */
     reset() {
         call("libgio-2.0.so.0", "g_converter_reset", [
             {
@@ -157,6 +271,47 @@ export class CharsetConverter extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Initializes the object implementing the interface.
+     *
+     * This method is intended for language bindings. If writing in C,
+     * g_initable_new() should typically be used instead.
+     *
+     * The object must be initialized before any real use after initial
+     * construction, either with this function or g_async_initable_init_async().
+     *
+     * Implementations may also support cancellation. If `cancellable` is not %NULL,
+     * then initialization can be cancelled by triggering the cancellable object
+     * from another thread. If the operation was cancelled, the error
+     * %G_IO_ERROR_CANCELLED will be returned. If `cancellable` is not %NULL and
+     * the object doesn't support cancellable initialization the error
+     * %G_IO_ERROR_NOT_SUPPORTED will be returned.
+     *
+     * If the object is not initialized, or initialization returns with an
+     * error, then all operations on the object except g_object_ref() and
+     * g_object_unref() are considered to be invalid, and have undefined
+     * behaviour. See the [description][iface@Gio.Initable#description] for more details.
+     *
+     * Callers should not assume that a class which implements #GInitable can be
+     * initialized multiple times, unless the class explicitly documents itself as
+     * supporting this. Generally, a class’ implementation of init() can assume
+     * (and assert) that it will only be called once. Previously, this documentation
+     * recommended all #GInitable implementations should be idempotent; that
+     * recommendation was relaxed in GLib 2.54.
+     *
+     * If a class explicitly supports being initialized multiple times, it is
+     * recommended that the method is idempotent: multiple calls with the same
+     * arguments should return the same results. Only the first call initializes
+     * the object; further calls return the result of the first call.
+     *
+     * One reason why a class might need to support idempotent initialization is if
+     * it is designed to be used via the singleton pattern, with a
+     * #GObjectClass.constructor that sometimes returns an existing instance.
+     * In this pattern, a caller would expect to be able to call g_initable_init()
+     * on the result of g_object_new(), regardless of whether it is in fact a new
+     * instance.
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     init(cancellable) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_initable_init", [