@gtkx/runtime 1.0.0-rc.2 → 1.0.0-rc.4

package/src/mixin.ts

@@ -1,7 +1,13 @@
 import type { AnyClass } from "@gtkx/utils";
 
+/**
+ * The signal plumbing every base class passed to a {@link Mixin} provides, so mixed-in interface
+ * members can connect and emit without knowing the concrete class.
+ */
 type MixinReceiver = {
+    /** Connects a handler to a signal and returns its handler id. */
     connect(signal: string, handler: (...args: unknown[]) => unknown, isAfter?: boolean): number;
+    /** Emits a signal with the given arguments and returns whatever the emission produced. */
     emit(signal: string, ...args: unknown[]): unknown;
 };
 
@@ -41,6 +47,12 @@ function copyLayerMember(target: AnyClass, layer: object, key: string): void {
     }
 }
 
+function copyLayerMembers(target: AnyClass, layer: object): void {
+    for (const key of Object.getOwnPropertyNames(layer)) {
+        copyLayerMember(target, layer, key);
+    }
+}
+
 /**
  * Copies each mixin's prototype members onto the target class prototype, skipping
  * any member already defined anywhere in the target's class chain.
@@ -48,12 +60,6 @@ function copyLayerMember(target: AnyClass, layer: object, key: string): void {
  * @param target The class whose prototype receives the mixin members.
  * @param mixins The mixins to apply, in order.
  */
-function copyLayerMembers(target: AnyClass, layer: object): void {
-    for (const key of Object.getOwnPropertyNames(layer)) {
-        copyLayerMember(target, layer, key);
-    }
-}
-
 function installMixins(target: AnyClass, mixins: Mixin[]): void {
     const empty: AnyClass<MixinReceiver> = class {
         connect(): number {

package/src/native-value.ts

@@ -111,6 +111,14 @@ function hashTableToNative(descriptor: HashTableDescriptor, value: unknown): unk
     ]);
 }
 
+/**
+ * Converts a JavaScript value into the raw form native code expects, unwrapping
+ * object, struct, boxed, and fundamental wrappers back to their handles and
+ * recursively converting arrays and maps according to the descriptor.
+ *
+ * @param descriptor Describes the native type to convert to.
+ * @param value The JavaScript value to convert.
+ */
 function toNative(descriptor: Descriptor, value: unknown): unknown {
     if (!isMarshalledDescriptor(descriptor)) {
         return value;

package/src/promisify.ts

@@ -1,10 +1,8 @@
 import { tryGetHandle } from "./registry.js";
 
 /**
- * Extracts the finished value from the async result a GIO-style operation completes with.
- *
- * @template R - The async result type passed to the completion callback.
- * @template T - The finished value type.
+ * Extracts the value of a completed asynchronous operation from its `GAsyncResult`, throwing when
+ * the operation failed.
  */
 type FinishResult<R extends object, T> = (result: R) => T;
 
@@ -57,11 +55,11 @@ const promisify = <R extends object, T>(
 ): Promise<T> =>
     new Promise<T>((resolve, reject) => {
         const creationStack =
-            process.env.NODE_ENV === "production" ? undefined : new Error("gtkx async operation started here");
+            process.env.NODE_ENV === "production" ? undefined : new Error("GTKX async operation started here");
 
         asyncFn(...leading, tryGetHandle(cancellable), (_source: object | null, asyncResult: object) => {
             settle({ finish, creationStack, resolve, reject }, asyncResult);
         });
     });
 
-export { promisify, type FinishResult };
+export { promisify };

package/src/properties.ts

@@ -12,6 +12,7 @@ type PropertyAccessor = {
     pspec: object;
 };
 
+/** A `GObject.ParamSpec` wrapper describing one property's name, type, flags and default. */
 type PropertySpec = object;
 type NotifyingObject = { notify?: (propertyName: string) => void };
 

package/src/register-class.ts

@@ -23,13 +23,14 @@ import {
 } from "./registry.js";
 import { TYPE_INVALID, typeInterfaces } from "./type.js";
 
+/** What {@link registerClass} adds to the new GType beyond the vtable slots it discovers on the class. */
 type RegisterClassOptions = {
+    /** Name to register the new GType under, defaulting to the class's own name. */
     typeName?: string;
     /**
-     * Properties to install on the new type, keyed by canonical property name. Each value is the
-     * `GObject.ParamSpec` describing it, for example `GObject.paramSpecString(...)`. Accessors are
-     * generated on the prototype for the dashed, underscored and camelCased spellings of the name
-     * unless the class already defines one, and writing through them emits `notify`.
+     * Properties to install on the new type, keyed by canonical name and valued with the
+     * `GObject.ParamSpec` describing each. Every property gains dashed, underscored and camelCased
+     * prototype accessors that emit `notify` on write, unless the class already defines that name.
      */
     properties?: Record<string, PropertySpec>;
 };
@@ -50,7 +51,6 @@ const VALUE_ARG_INDEX = 2;
  * unsupported construct-time vtable slot.
  *
  * @param klass The subclass to register.
- * @param options Registration options, such as an explicit type name.
  * @returns The same class, now registered.
  */
 function registerClass<T extends AnyClass>(klass: T, options: RegisterClassOptions = {}): T {
@@ -237,11 +237,9 @@ function propertyVfuncs(klass: AnyClass, accessors: PropertyAccessor[]): Discove
     ];
 }
 
-// `get_property` fills a GValue the caller owns, so the marshalled copy handed to JavaScript has to
-// be written back into it; `set_property` only reads its GValue and needs no copy back.
 function markValueCallerAllocated(argDescriptors: Descriptor[]): Descriptor[] {
     return argDescriptors.map((arg, index) =>
-        index === VALUE_ARG_INDEX ? { ...arg, callerAllocated: true } : arg);
+        index === VALUE_ARG_INDEX ? { ...arg, isCallerAllocated: true } : arg);
 }
 
 function buildPropertyVfunc(

package/src/registry.ts

@@ -17,16 +17,28 @@ import { TYPE_INVALID, type TypedClass, typeInterfaces, typeIsA, typeName, typeP
 type StaticBase<C, K extends PropertyKey = "new"> = Omit<C, K> &
     (C extends new (...args: infer A) => infer R ? new (...args: A) => R : never);
 
+/** One overridable vtable slot: where it sits in the vtable struct and how it is marshalled. */
 type VfuncDescriptor<K extends "class" | "interface"> = {
+    /** Whether the slot lives in a class struct or in an interface vtable. */
     kind: K;
+    /** GIR name of the type struct holding the slot, without its namespace, such as `WidgetClass`. */
     className: string;
+    /** Name of the slot's field in that struct. */
     vfuncName: string;
+    /** Byte offset of the slot within the struct. */
     byteOffset: number;
+    /** Byte size of the struct, used to bounds-check `VfuncDescriptor.byteOffset`. */
     vtableSize: number;
+    /** Descriptor for each argument the slot receives, starting with the instance. */
     argDescriptors: NativeRegisterClassVfunc["argDescriptors"];
+    /** Descriptor for the value the slot returns. */
     returnDescriptor: NativeRegisterClassVfunc["returnDescriptor"];
 };
 
+/**
+ * The vtable slots a wrapper class or interface exposes, keyed by the JavaScript method name that
+ * overrides each one.
+ */
 type VfuncRegistry = Record<string, VfuncDescriptor<"class"> | VfuncDescriptor<"interface">>;
 
 const classRegistry: Map<bigint, AnyClass> = new Map();
@@ -65,7 +77,8 @@ function registerClassType(cls: AnyClass, type: bigint): void {
  * installing a registry of virtual functions.
  * @param cls Wrapper class to associate with the type.
  * @param type GType the class wraps.
- * @param vfuncs Virtual functions the class overrides.
+ * @param vfuncs Vtable slots the class exposes, so `registerClass` can bind the ones a subclass
+ * overrides.
  */
 function registerWrapperClass(cls: AnyClass, type: bigint, vfuncs?: VfuncRegistry): void {
     registerClassType(cls, type);
@@ -81,7 +94,8 @@ function registerWrapperClass(cls: AnyClass, type: bigint, vfuncs?: VfuncRegistr
  * @param cls Class carrying the interface's GType tag.
  * @param type GType of the interface.
  * @param mixin Mixin that applies the interface to a wrapper class.
- * @param vfuncs Virtual functions the interface exposes.
+ * @param vfuncs Vtable slots the interface exposes, so `registerClass` can bind the ones an
+ * implementing class overrides.
  */
 function registerInterface(cls: AnyClass, type: bigint, mixin: Mixin, vfuncs?: VfuncRegistry): void {
     if (type === TYPE_INVALID) {

package/src/signal.ts

@@ -30,13 +30,27 @@ import {
 /** Function invoked when a connected GObject signal is emitted. */
 type SignalHandler = (...args: unknown[]) => unknown;
 
+/** The marshalling and handler that make up a single signal connection. */
 type SignalConnectSpec = {
+    /**
+     * Marshalling for the emission, whose `argDescriptors` lead with the emitter and include the
+     * closure's user data slot.
+     */
     callback: CallbackDescriptor;
+    /** Called on each emission with the signal's own arguments, without the leading emitter. */
     handler: SignalHandler;
-    after: boolean;
+    /** When true, run the handler after the class's default handler instead of before it. */
+    isAfter: boolean;
 };
 
-type EmitArg = Arg & { value?: unknown };
+/** One argument of a signal emission: how to marshal it, plus the value to marshal. */
+type EmitArg = Arg & {
+    /**
+     * The value to pass for an input or inout argument, or the caller-allocated storage to fill for
+     * a caller-allocated output argument; omitted for a plain output argument.
+     */
+    value?: unknown;
+};
 
 const connectCache = createBindCache();
 const gQuarkFromString = bind(LIB, "g_quark_from_string", [stringT("borrowed")], uint32T);
@@ -108,12 +122,12 @@ function connectBind(type: bigint, signal: string, callback: CallbackDescriptor)
  * @param spec Callback descriptor, handler function, and whether to run after the default handler.
  */
 function connectSignal(instance: object, signal: string, spec: SignalConnectSpec): number {
-    const { callback, handler, after } = spec;
+    const { callback, handler, isAfter } = spec;
     const wrapped = wrapCallback(handler, callback, "emitter");
     const type: bigint = (instance as TypedClass).__type__;
     const connect = connectBind(type, signal, callback);
 
-    return connect(getHandle(instance), signal, wrapped, after ? 1 : 0) as number;
+    return connect(getHandle(instance), signal, wrapped, isAfter ? 1 : 0) as number;
 }
 
 function blockMatchedSignalHandlers(instance: object, signal: string): void {

package/src/t.ts

@@ -2,43 +2,87 @@ import { bind } from "./bind.js";
 import * as helpers from "./descriptors.js";
 import { fn } from "./fn.js";
 
+/** The descriptor factories and function binders exposed as {@link t}. */
 type T = {
+    /** Binds a symbol in a shared library to a callable that marshals its arguments and return value. */
     bind: typeof bind;
+    /** Descriptor for a `gint8`, marshalled as a number. */
     int8: typeof helpers.int8T;
+    /** Descriptor for a `guint8`, marshalled as a number. */
     uint8: typeof helpers.uint8T;
+    /** Descriptor for a `gint16`, marshalled as a number. */
     int16: typeof helpers.int16T;
+    /** Descriptor for a `guint16`, marshalled as a number. */
     uint16: typeof helpers.uint16T;
+    /** Descriptor for a `gint32`, marshalled as a number. */
     int32: typeof helpers.int32T;
+    /** Descriptor for a `guint32`, marshalled as a number. */
     uint32: typeof helpers.uint32T;
+    /** Descriptor for a `gint64`, marshalled as a number and rejected outside the 2^53 safe range. */
     int64: typeof helpers.int64T;
+    /** Descriptor for a `guint64`, marshalled as a number and rejected outside the 2^53 safe range. */
     uint64: typeof helpers.uint64T;
+    /** Descriptor for a `gint64`, marshalled as a bigint so the full 64-bit range survives. */
     bigint64: typeof helpers.bigint64T;
+    /** Descriptor for a `guint64`, marshalled as a bigint so the full 64-bit range survives. */
     biguint64: typeof helpers.biguint64T;
+    /** Descriptor for a `GType`, marshalled as a bigint and recognized as a GType by GValue conversion. */
     gtype: typeof helpers.gtypeT;
+    /** Descriptor for a `gfloat`. */
     float32: typeof helpers.float32T;
+    /** Descriptor for a `gdouble`. */
     float64: typeof helpers.float64T;
+    /** Descriptor for a `gboolean`, marshalled as a JavaScript boolean. */
     boolean: typeof helpers.booleanT;
+    /** Descriptor for the absence of a value, used as the return descriptor of a `void` function. */
     void: typeof helpers.voidT;
+    /** Descriptor for a `gunichar`, marshalled as a single-character string or a codepoint number. */
     unichar: typeof helpers.unicharT;
+    /** Descriptor for an opaque `gpointer` argument, taken from a typed array's memory or a numeric address. */
     buffer: typeof helpers.bufferT;
+    /**
+     * Builds a descriptor for a C string, whose optional length sizes the caller-allocated buffer
+     * used when the string is passed by reference.
+     */
     string: typeof helpers.stringT;
+    /** Builds a descriptor for a `GObject`, wrapped in the class registered for its runtime GType. */
     object: typeof helpers.objectT;
+    /** Builds a descriptor for a `GBoxed` value of the named type. */
     boxed: typeof helpers.boxedT;
+    /** Builds a descriptor for a plain C struct. */
     struct: typeof helpers.structT;
+    /** Builds a descriptor for a fundamental type whose lifetime is managed by named ref and unref functions. */
     fundamental: typeof helpers.fundamentalT;
+    /** Wraps a descriptor in a pointer to it, for an output or inout argument. */
     ref: typeof helpers.refT;
+    /** Builds a descriptor for a `GHashTable`, marshalled as an array of key/value pairs. */
     hashTable: typeof helpers.hashTableT;
+    /** Builds a descriptor for an enumeration, resolving its GType from the named `get_type` function. */
     enum: typeof helpers.enumT;
+    /** Builds a descriptor for a flags type, resolving its GType from the named `get_type` function. */
     flags: typeof helpers.flagsT;
+    /** Builds a descriptor for an array of items in one of the supported container layouts. */
     array: typeof helpers.arrayT;
+    /** Builds a descriptor for a `GList` of items. */
     list: typeof helpers.listT;
+    /** Builds a descriptor for a `GSList` of items. */
     slist: typeof helpers.slistT;
+    /** Builds a descriptor for a `GPtrArray` of items. */
     ptrArray: typeof helpers.ptrArrayT;
+    /** Builds a descriptor for a `GArray` of items, optionally with an explicit element size. */
     gArray: typeof helpers.gArrayT;
+    /** Builds a descriptor for a `GByteArray`. */
     byteArray: typeof helpers.byteArrayT;
+    /** Builds a descriptor for a C array whose length is carried by another argument. */
     sizedArray: typeof helpers.sizedArrayT;
+    /** Builds a descriptor for a C array of a fixed length. */
     fixedArray: typeof helpers.fixedArrayT;
+    /** Builds a descriptor for a function pointer, marshalling a JavaScript function into a native closure. */
     callback: typeof helpers.callbackT;
+    /**
+     * Binds a native function, wiring up argument directions, `GError` checking, and packing output
+     * arguments into the result.
+     */
     fn: typeof fn;
 };
 

package/src/type.ts

@@ -19,7 +19,6 @@ type TypedClass = {
 };
 
 type ResolvableKind = "enum" | "flags" | "boxed" | "fundamental" | "array";
-/** Descriptor kinds whose GType is resolved from library metadata rather than a fixed fundamental type. */
 type ResolvableDescriptor = Extract<Descriptor, { kind: ResolvableKind }>;
 
 const resolvedTypeCache: Map<string, bigint> = new Map();

package/src/value.ts

@@ -209,8 +209,8 @@ const newBoxedValue = (
 };
 
 /**
- * Reads the boxed pointer out of a GValue and returns it wrapped in its registered
- * class, or null when the value does not hold a boxed type.
+ * Duplicates the boxed value held by a GValue and returns the copy wrapped in the
+ * class registered for its GType, or null when the GValue holds no boxed type.
  */
 function getBoxedValue(value: ExternalObject<Handle>): object | null {
     const type = getValueType(value);
@@ -325,13 +325,6 @@ const resolveValueGetter = (fundamental: bigint): ValueGetter | undefined =>
 const resolveValueSetter = (fundamental: bigint): ValueType["set"] | undefined =>
     PLAIN_VALUE_SETTERS.get(fundamental) ?? WRAPPED_VALUE_SETTERS.get(fundamental);
 
-/**
- * Stores a JavaScript value into an already-initialized GValue, converting it to
- * whatever type the GValue holds.
- *
- * @param value The initialized GValue to write into.
- * @param jsValue The JavaScript value to store.
- */
 function intoValue(value: ExternalObject<Handle>, jsValue: unknown): void {
     const type = getValueType(value);
     const set = resolveValueSetter(typeFundamental(type));