@gtkx/codegen 1.0.0-rc.4 → 1.1.0

package/src/gir/libraries.ts

@@ -1,11 +1,19 @@
 import { sortStrings } from "@gtkx/utils";
 import { readdirSync } from "node:fs";
 
-type GirNamespace = { name: string; version: string; identifier: string };
+/** A namespace found on the GIR path, taken from the name of its `.gir` file. */
+type GirNamespace = {
+    /** Namespace the file describes, such as `Gtk`. */
+    name: string;
+    /** API version the file describes, such as `4.0`. */
+    version: string;
+    /** Name and version joined the way a `libraries` entry spells them, such as `Gtk-4.0`. */
+    identifier: string;
+};
+
 /** A `libraries` config value: an explicit list, `"*"` for everything installed, or absent for the default. */
-type LibrarySelection = typeof LIBRARIES_WILDCARD | string[] | undefined;
+type LibrarySelection = "*" | string[] | undefined;
 
-/** The `libraries` value that stands for every GIR library installed on the search path. */
 const LIBRARIES_WILDCARD = "*";
 const GIR_LIBRARY_PATTERN = /^[A-Za-z][A-Za-z0-9]*-\d+(?:\.\d+)*$/;
 const DEFAULT_LIBRARIES: string[] = ["Gtk-4.0"];

package/src/gir/library.ts

@@ -14,13 +14,23 @@ import {
 import { parseGirFile, type RawNode } from "./parse.js";
 import { splitOptionalNamespace } from "./type-ref.js";
 
+/** The types belonging to one namespace, addressed by the id half of a {@link TypeId}. */
 type TypeTable = {
+    /** Parsed type in each slot, still `undefined` while only a forward reference to it has been seen. */
     types: (GirType | undefined)[];
+    /** Declared name of each slot, `undefined` for anonymous types such as containers and inline callbacks. */
     names: (string | undefined)[];
+    /** Slot id each named type occupies, so repeated references resolve to the same id. */
     index: Map<string, number>;
 };
 
-type DiscoveredNamespace = { header: NamespaceHeader; shell: GirNamespace };
+/** A namespace whose header has been read and whose shell is registered, before its body is parsed. */
+type DiscoveredNamespace = {
+    /** Attributes and includes read from the namespace's GIR file. */
+    header: NamespaceHeader;
+    /** Empty namespace registered for the header, populated once every header is known. */
+    shell: GirNamespace;
+};
 
 const INTERNAL_NS_ID = 0;
 
@@ -50,6 +60,10 @@ const locateGirFile = (identifier: string, girPath: string[]): string => {
     throw new Error(`GIR file ${filename} not found on girPath. Tried: ${tried}`);
 };
 
+/**
+ * The parsed GIR universe: every requested namespace plus everything those namespaces include,
+ * with types resolvable across namespace boundaries.
+ */
 class Library {
     private static drive(library: Library, libraries: string[], girPath: string[]): void {
         const { discovered, girFiles } = library.discoverNamespaces(libraries, girPath);
@@ -65,6 +79,13 @@ class Library {
         library.girFilesValue = girFiles;
     }
 
+    /**
+     * Parses the named GIR libraries along with every namespace they transitively include.
+     *
+     * @param libraries GIR identifiers to load, such as `Gtk-4.0`.
+     * @param girPath Directories searched, in order, for each `.gir` file.
+     * @returns A library holding every namespace that was parsed.
+     */
     static load(libraries: string[], girPath: string[]): Library {
         const library = new Library();
         this.drive(library, libraries, girPath);
@@ -79,6 +100,7 @@ class Library {
     private typeTables: TypeTable[] = [];
     private girFilesValue: string[] = [];
 
+    /** Creates a library with no namespaces loaded; {@link Library.load} builds a populated one. */
     constructor() {
         this.typeTables[INTERNAL_NS_ID] = { types: [], names: [], index: new Map() };
         this.namespaceById[INTERNAL_NS_ID] = undefined;
@@ -272,7 +294,7 @@ class Library {
         seen.add(namespaceName);
         const path = locateGirFile(identifier, girPath);
         girFiles.push(path);
-        const header = parseNamespaceHeader(readRepositoryNode(path));
+        const header = parseNamespaceHeader(readRepositoryNode(path), path);
         const shell = this.registerNamespace(header);
         discovered.push({ header, shell });
 
@@ -301,19 +323,38 @@ class Library {
         return { discovered, girFiles };
     }
 
+    /** The loaded namespaces, keyed by their GIR name such as `Gtk`. */
     public get namespaces(): Map<string, GirNamespace> {
         return this.namespacesByName;
     }
 
+    /** Paths of the `.gir` files that were read, in the order they were discovered. */
     public get girFiles(): string[] {
         return this.girFilesValue;
     }
 
+    /**
+     * Reads the type a {@link TypeId} points at.
+     *
+     * @param tid The type id to dereference.
+     * @returns The parsed type, or `undefined` when nothing has been parsed into that slot.
+     */
     typeFor(tid: TypeId): GirType | undefined {
         return this.typeTables[tid.nsId]?.types[tid.id];
     }
 
-    nameFor(tid: TypeId): { namespaceName: string; typeName: string } | undefined {
+    /**
+     * Reads the name a {@link TypeId} was registered under.
+     *
+     * @param tid The type id to name.
+     * @returns The namespace and type name, or `undefined` for an anonymous type.
+     */
+    nameFor(tid: TypeId): {
+        /** GIR namespace to qualify the type with, such as `Gtk`. */
+        namespaceName: string;
+        /** Unqualified type name as GIR declares it, such as `Widget`. */
+        typeName: string;
+    } | undefined {
         const typeName = this.typeTables[tid.nsId]?.names[tid.id];
         const namespaceName = this.nsNameById[tid.nsId];
 
@@ -324,6 +365,14 @@ class Library {
         return { namespaceName, typeName };
     }
 
+    /**
+     * Looks up a type by the name a GIR file writes, resolving an unqualified name against the
+     * namespace it appears in and a `Namespace.Type` name against the loaded namespaces.
+     *
+     * @param currentNamespaceName Namespace the name is written in.
+     * @param name Type name, optionally qualified with a namespace prefix.
+     * @returns The parsed type, or `undefined` when the name is unknown or only a forward reference to it exists.
+     */
     resolveType(currentNamespaceName: string, name: string): GirType | undefined {
         const currentNsId = this.nsIdByName.get(currentNamespaceName);
 

package/src/gir/namespace.ts

@@ -1,58 +1,100 @@
 import type { ParseContext, TypeId } from "./type-id.js";
+import { documentedFromNode, type GirAnnotations } from "./annotations.js";
 import { callbackFromNode, type GirCallback } from "./callback.js";
 import { classFromNode, type GirClass } from "./class.js";
 import { enumFromNode, type GirEnum } from "./enum.js";
 import { functionFromNode, type GirFunction } from "./function.js";
-import { attr, getChild, getChildren, getDoc, nameAttr, type RawNode } from "./parse.js";
+import { attr, getChild, getChildren, nameAttr, type RawNode } from "./parse.js";
 import { type GirRecord, isVtableRecord, recordFromNode } from "./record.js";
 import { typeRefFromNode } from "./type-ref.js";
 
+/** A compile-time constant declared by a namespace. */
 type GirConstant = {
+    /** Local name within the namespace. */
     name: string;
+    /** Documentation text carried by the GIR node. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the constant. */
+    annotations: GirAnnotations;
+    /** Literal as written in the GIR, still to be interpreted according to {@link GirConstant.type}. */
     value: string;
+    /** Type of the constant, unresolved until looked up in the library's type tables. */
     type: TypeId | undefined;
 };
 
+/** A named alias for another type. */
 type GirAlias = {
+    /** Local name within the namespace. */
     name: string;
+    /** Documentation text carried by the GIR node. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the alias. */
+    annotations: GirAnnotations;
+    /** C typedef name introduced by the alias. */
     cType: string | undefined;
+    /** Type the alias stands for, unresolved until looked up in the library's type tables. */
     target: TypeId | undefined;
+    /** C type name of the target, which decides how the alias marshals. */
     targetCType: string | undefined;
 };
 
+/** Everything one GIR namespace declares, keyed into the library that parsed it. */
 type GirNamespace = {
+    /** Identifier of the namespace's type table within its library. */
     id: number;
+    /** Namespace name as it appears in the GIR, such as `Gtk`. */
     name: string;
+    /** Path of the `.gir` file the namespace was parsed from, named by every diagnostic the namespace causes. */
+    girFile: string;
+    /** The `shared-library` attribute verbatim: the objects to load symbols from, separated by commas. */
     sharedLibrary: string | undefined;
+    /** Prefixes stripped off C identifiers to derive export names, such as `gtk`. */
     cSymbolPrefixes: string[];
+    /** GObject classes declared by the namespace. */
     classes: GirClass[];
+    /** GObject interfaces declared by the namespace. */
     interfaces: GirClass[];
+    /** Structs and unions declared by the namespace. */
     records: GirRecord[];
+    /** Enumerations and bitfields declared by the namespace. */
     enums: GirEnum[];
+    /** Callback types declared by the namespace. */
     callbacks: GirCallback[];
+    /** Free functions declared by the namespace. */
     functions: GirFunction[];
+    /** Compile-time values, emitted as module-level `const` bindings. */
     constants: GirConstant[];
+    /** Typedefs, emitted as TypeScript type aliases and resolvable as types themselves. */
     aliases: GirAlias[];
 };
 
+/** Another namespace a GIR repository depends on. */
 type NamespaceInclude = {
+    /** Name of the included namespace, such as `Gio`. */
     name: string;
+    /** Version of the included namespace, such as `2.0`. */
     version: string;
 };
 
+/** A namespace's declaration and dependencies, read before its body is parsed. */
 type NamespaceHeader = {
+    /** Namespace name as it appears in the GIR, such as `Gtk`. */
     name: string;
+    /** Path of the `.gir` file the header was read from. */
+    girFile: string;
+    /** The `shared-library` attribute verbatim: the objects to load symbols from, separated by commas. */
     sharedLibrary: string | undefined;
+    /** Prefixes stripped off C identifiers to derive export names, such as `gtk`. */
     cSymbolPrefixes: string[];
+    /** Namespaces this repository includes, each of which is parsed in turn. */
     includes: NamespaceInclude[];
+    /** The `<namespace>` node whose children hold the declarations. */
     namespaceNode: RawNode;
 };
 
 const namespaceDirectory = (namespace: Pick<GirNamespace, "name">): string => namespace.name.toLowerCase();
 
-const parseNamespaceHeader = (repositoryNode: RawNode): NamespaceHeader => {
+const parseNamespaceHeader = (repositoryNode: RawNode, path: string): NamespaceHeader => {
     const includes = getChildren(repositoryNode, "include").map<NamespaceInclude>((include) => ({
         name: nameAttr(include),
         version: attr(include, "version") ?? "",
@@ -61,11 +103,12 @@ const parseNamespaceHeader = (repositoryNode: RawNode): NamespaceHeader => {
     const namespaceNode = getChildren(repositoryNode, "namespace")[0];
 
     if (namespaceNode === undefined) {
-        throw new Error("GIR repository has no <namespace> child");
+        throw new Error(`GIR file at ${path} has no <namespace> child in its <repository>`);
     }
 
     return {
         name: nameAttr(namespaceNode),
+        girFile: path,
         sharedLibrary: attr(namespaceNode, "shared-library"),
         cSymbolPrefixes: splitPrefixes(attr(namespaceNode, "c:symbol-prefixes")),
         includes,
@@ -76,6 +119,7 @@ const parseNamespaceHeader = (repositoryNode: RawNode): NamespaceHeader => {
 const createNamespaceShell = (header: NamespaceHeader, id: number): GirNamespace => ({
     id,
     name: header.name,
+    girFile: header.girFile,
     sharedLibrary: header.sharedLibrary,
     cSymbolPrefixes: header.cSymbolPrefixes,
     classes: [],
@@ -97,15 +141,13 @@ const populateNamespaceBody = (shell: GirNamespace, namespaceNode: RawNode, cont
     shell.functions = getChildren(namespaceNode, "function").map((fn) => functionFromNode(fn, context));
 
     shell.constants = getChildren(namespaceNode, "constant").map((constant) => ({
-        name: nameAttr(constant),
-        doc: getDoc(constant),
+        ...documentedFromNode(constant),
         value: attr(constant, "value") ?? "",
         type: typeRefFromNode(constant, context),
     }));
 
     shell.aliases = getChildren(namespaceNode, "alias").map((alias) => ({
-        name: nameAttr(alias),
-        doc: getDoc(alias),
+        ...documentedFromNode(alias),
         cType: attr(alias, "c:type"),
         target: typeRefFromNode(alias, context),
         targetCType: attr(getChild(alias, "type"), "c:type"),

package/src/gir/parameter.ts

@@ -1,4 +1,5 @@
 import type { ParseContext, TypeId } from "./type-id.js";
+import { documentedFromNode, type GirAnnotations } from "./annotations.js";
 import {
     attr,
     getChild,
@@ -12,37 +13,88 @@ import {
 } from "./parse.js";
 import { typeRefFromNode } from "./type-ref.js";
 
+/** Which way a parameter's value travels: into the call, back out of it, or both. */
 type ParameterDirection = "in" | "out" | "inout";
+/** How much of a value the receiver takes ownership of: none, the whole value, or only its container. */
 type ParameterTransfer = "none" | "full" | "container";
+/**
+ * How long a callback parameter stays valid: for the duration of the call, until its destroy notify runs,
+ * until the asynchronous operation invokes it, or forever.
+ */
 type CallbackScope = "call" | "notified" | "async" | "forever";
 
+/**
+ * Bounds of an out parameter that points into the buffer of a sibling parameter instead of to an
+ * array of its own, which GIR describes as an array with no extent of any kind.
+ */
+type GirCursorBounds = {
+    /** Position of the parameter holding the buffer the pointer points into. */
+    baseIndex: number;
+    /** Position of the parameter carrying that buffer's element count. */
+    lengthIndex: number;
+};
+
+/** A parameter of a {@link GirCallable}, with the annotations that decide how it is marshalled. */
 type GirParameter = {
+    /** The name GIR gives the parameter. */
     name: string;
+    /** What the parameter holds, absent when the GIR node declares no type. */
     type: TypeId | undefined;
+    /** The C spelling of the parameter's type, taken from its `type` or `array` child. */
+    cType: string | undefined;
+    /** Documentation prose from GIR, emitted as the parameter's `@param` text. */
+    doc: string | undefined;
+    /** Decides whether the parameter is an argument, part of the returned tuple, or both. */
     direction: ParameterDirection;
+    /** Ownership the marshalling descriptor is generated with, deciding whether the receiver frees the value. */
     transferOwnership: ParameterTransfer;
+    /** Whether the value may be null. */
     nullable: boolean;
+    /** Whether the caller may leave the parameter out entirely. */
     optional: boolean;
+    /** Whether the caller supplies the storage an out parameter writes into. */
     callerAllocates: boolean;
+    /** How long a callback parameter stays valid, absent when GIR carries no scope annotation. */
     scope: CallbackScope | undefined;
+    /** Position of the parameter carrying the callback's user data. */
     closureIndex: number | undefined;
+    /** Position of the parameter carrying the callback's destroy notify. */
     destroyIndex: number | undefined;
+    /** Whether the parameter is the `...` varargs marker. */
     isVarargs: boolean;
+    /** Where the buffer is that the parameter points into, when it carries a cursor rather than an array. */
+    cursor: GirCursorBounds | undefined;
 };
 
+/** What a {@link GirCallable} hands back, with the annotations that decide how it is marshalled. */
 type GirReturnValue = {
+    /** What the callable returns, absent when the GIR node declares no type. */
     type: TypeId | undefined;
+    /** Documentation prose from GIR, emitted as the callable's `@returns` text. */
+    doc: string | undefined;
+    /** How much ownership the caller takes of the returned value. */
     transferOwnership: ParameterTransfer;
+    /** Whether the returned value may be null. */
     nullable: boolean;
+    /** Whether GIR marks the value as skipped, keeping it out of the generated signature. */
     skip: boolean;
 };
 
+/** Anything GIR describes with parameters and a return value: functions, methods, signals, and callbacks. */
 type GirCallable = {
+    /** The name GIR gives the callable. */
     name: string;
+    /** The callable's documentation text, absent when GIR carries none. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the callable. */
+    annotations: GirAnnotations;
+    /** The parameters the callable takes, in declaration order. */
     parameters: GirParameter[];
+    /** What the callable hands back. */
     returnValue: GirReturnValue;
+    /** Whether the callable reports failure through a trailing `GError`. */
     throws: boolean;
+    /** Whether GIR exposes the callable to bindings. */
     introspectable: boolean;
 };
 
@@ -62,9 +114,14 @@ const hasNullableAttr = (node: RawNode): boolean =>
 const hasOptionalAttr = (node: RawNode): boolean =>
     isAttrTrue(node, "optional") || (!isInDirection(node) && isAttrTrue(node, "allow-none"));
 
+const parameterCType = (node: RawNode): string | undefined =>
+    attr(getChild(node, "type"), "c:type") ?? attr(getChild(node, "array"), "c:type");
+
 const parameterFromNode = (node: RawNode, context: ParseContext): GirParameter => ({
     name: nameAttr(node),
     type: typeRefFromNode(node, context),
+    cType: parameterCType(node),
+    doc: getDoc(node),
     direction: parseEnumAttr(attr(node, "direction"), DIRECTIONS, "in", "direction"),
     transferOwnership: transferOwnership(node),
     nullable: hasNullableAttr(node),
@@ -74,6 +131,7 @@ const parameterFromNode = (node: RawNode, context: ParseContext): GirParameter =
     closureIndex: intAttr(node, "closure"),
     destroyIndex: intAttr(node, "destroy"),
     isVarargs: getChild(node, "varargs") !== undefined,
+    cursor: undefined,
 });
 
 const isOutParameter = (parameter: GirParameter): boolean =>
@@ -86,11 +144,12 @@ const isInoutParameter = (parameter: GirParameter): boolean => parameter.directi
 
 const returnValueFromNode = (node: RawNode | undefined, context: ParseContext): GirReturnValue => {
     if (node === undefined) {
-        return { type: undefined, transferOwnership: "none", nullable: false, skip: false };
+        return { type: undefined, doc: undefined, transferOwnership: "none", nullable: false, skip: false };
     }
 
     return {
         type: typeRefFromNode(node, context),
+        doc: getDoc(node),
         transferOwnership: transferOwnership(node),
         nullable: hasNullableAttr(node),
         skip: isAttrTrue(node, "skip"),
@@ -102,8 +161,7 @@ const parseCallable = (node: RawNode, context: ParseContext): GirCallable => {
     const parameterNodes = getChildren(parametersNode, "parameter");
 
     return {
-        name: nameAttr(node),
-        doc: getDoc(node),
+        ...documentedFromNode(node),
         parameters: parameterNodes.map((parameter) => parameterFromNode(parameter, context)),
         returnValue: returnValueFromNode(getChild(node, "return-value"), context),
         throws: isAttrTrue(node, "throws"),
@@ -119,6 +177,7 @@ export {
     isInoutParameter,
     parseCallable,
     type ParameterTransfer,
+    type GirCursorBounds,
     type GirParameter,
     type GirReturnValue,
     type GirCallable,

package/src/gir/parse.ts

@@ -1,8 +1,10 @@
-import { readFileSync } from "node:fs";
-import { createXmlParser } from "../xml.js";
+import { createXmlParser, parseXmlFile } from "../xml.js";
 
+/** An element of the parsed GIR XML: attributes under `@_`-prefixed keys, children under their tag names. */
 type RawNode = Record<string, unknown>;
 
+const GIR_LABEL = "GIR file";
+
 const MULTI_TAGS: Set<string> = new Set([
     "include",
     "class",
@@ -16,6 +18,7 @@ const MULTI_TAGS: Set<string> = new Set([
     "alias",
     "union",
     "method",
+    "virtual-method",
     "constructor",
     "property",
     "field",
@@ -40,11 +43,8 @@ function renameReservedTag(tag: string): string {
     return RESERVED_TAG_RENAMES.get(tag) ?? tag;
 }
 
-const parseGirFile = (path: string): RawNode => {
-    const xml = readFileSync(path, "utf8");
-
-    return PARSER.parse(xml) as RawNode;
-};
+const parseGirFile = (path: string): RawNode =>
+    parseXmlFile({ parser: PARSER, label: GIR_LABEL, path }) as RawNode;
 
 const attr = (node: RawNode | undefined, name: string): string | undefined => {
     if (node === undefined) {
@@ -141,12 +141,12 @@ const docTextFromObject = (value: object): string | undefined => {
     return typeof text === "string" ? normalizeDoc(text) : undefined;
 };
 
-const getDoc = (node: RawNode | undefined): string | undefined => {
+const docElementText = (node: RawNode | undefined, tag: string): string | undefined => {
     if (node === undefined) {
         return undefined;
     }
 
-    const value = firstDocValue(node.doc);
+    const value = firstDocValue(node[tag]);
 
     if (typeof value === "string") {
         return normalizeDoc(value);
@@ -159,6 +159,9 @@ const getDoc = (node: RawNode | undefined): string | undefined => {
     return docTextFromObject(value);
 };
 
+const getDoc = (node: RawNode | undefined): string | undefined => docElementText(node, "doc");
+const getDocDeprecated = (node: RawNode | undefined): string | undefined => docElementText(node, "doc-deprecated");
+
 export {
     GIR_CONSTRUCTOR_TAG,
     parseGirFile,
@@ -170,5 +173,6 @@ export {
     getChildren,
     getChild,
     getDoc,
+    getDocDeprecated,
     type RawNode,
 };

package/src/gir/primitives.ts

@@ -1,3 +1,4 @@
+/** A fundamental C type GIR can name, collapsed to the marshalling category GTKX treats it as. */
 type PrimitiveCategory =
     | "void" |
     "boolean" |

package/src/gir/property.ts

@@ -1,20 +1,36 @@
 import type { ParseContext, TypeId } from "./type-id.js";
+import { documentedFromNode, type GirAnnotations } from "./annotations.js";
 import { type ParameterTransfer, transferOwnership } from "./parameter.js";
-import { attr, getDoc, isAttrTrue, nameAttr, type RawNode } from "./parse.js";
+import { attr, isAttrTrue, type RawNode } from "./parse.js";
 import { typeRefFromNode } from "./type-ref.js";
 
+/** A GObject property declared on a class or interface, with the annotations its accessors are generated from. */
 type GirProperty = {
+    /** Canonical property name, dashed the way GObject registers it. */
     name: string;
+    /** Documentation prose from GIR, emitted as the accessor's JSDoc. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the property. */
+    annotations: GirAnnotations;
+    /** The property's value type, absent when GIR declares none. */
     type: TypeId | undefined;
+    /** Whether GObject exposes the value for reading, which admits a generated getter. */
     readable: boolean;
+    /** Whether GObject accepts a value for the property, which admits a generated setter. */
     writable: boolean;
+    /** Whether GObject sets the property during construction, using its default when none is supplied. */
     construct: boolean;
+    /** Whether the property can only be set at construction. */
     constructOnly: boolean;
+    /** Whether GIR exposes the property to bindings. */
     introspectable: boolean;
+    /** How ownership of the value transfers, which decides the descriptor the accessors marshal through. */
     transferOwnership: ParameterTransfer;
+    /** Method GIR names as reading the property, which the generated getter delegates to. */
     getter: string | undefined;
+    /** Method GIR names as writing the property, which the generated setter delegates to. */
     setter: string | undefined;
+    /** The property's default, as GIR spells it. */
     defaultValue: string | undefined;
 };
 
@@ -22,8 +38,7 @@ const isConstructableProperty = (property: GirProperty): boolean =>
     property.writable || property.construct || property.constructOnly;
 
 const propertyFromNode = (node: RawNode, context: ParseContext): GirProperty => ({
-    name: nameAttr(node),
-    doc: getDoc(node),
+    ...documentedFromNode(node),
     type: typeRefFromNode(node, context),
     readable: isAttrTrue(node, "readable", true),
     writable: isAttrTrue(node, "writable"),

package/src/gir/record.ts

@@ -1,26 +1,48 @@
 import type { ParseContext } from "./type-id.js";
+import { documentedFromNode, type GirAnnotations } from "./annotations.js";
 import { collectFields, type GirField } from "./field.js";
 import { functionFromNode, type GirFunction } from "./function.js";
-import { attr, getChildren, getDoc, GIR_CONSTRUCTOR_TAG, isAttrTrue, type RawNode } from "./parse.js";
+import { attr, getChildren, GIR_CONSTRUCTOR_TAG, isAttrTrue, type RawNode } from "./parse.js";
 
+/** A C struct or union declared by a GIR namespace: a plain record, a boxed type, or a GObject vtable. */
 type GirRecord = {
+    /** Whether the record is the class or interface struct holding another type's virtual methods. */
     isVtable: boolean;
+    /** Name within the declaring namespace, such as `"TextIter"`. */
     name: string;
+    /** Raw gtk-doc text from the GIR, undefined when the record is undocumented. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the record. */
+    annotations: GirAnnotations;
+    /** C struct name, such as `"GtkTextIter"`. */
     cType: string | undefined;
+    /** GLib type name the record is registered under, present when it is a boxed type. */
     glibTypeName: string | undefined;
+    /** Name of the function registering the record's GType, such as `"gtk_text_iter_get_type"`. */
     glibGetType: string | undefined;
+    /** Name of the function taking a reference, for reference-counted records. */
     glibRefFunc: string | undefined;
+    /** Name of the function dropping a reference, for reference-counted records. */
     glibUnrefFunc: string | undefined;
+    /** Name of the function duplicating an instance, used when the record has no ref function. */
     copyFunc: string | undefined;
+    /** Name of the function releasing an instance, used when the record has no unref function. */
     freeFunc: string | undefined;
+    /** Whether the struct is only ever handled behind a pointer, so its layout stays hidden. */
     disguised: boolean;
+    /** Whether the struct's fields are private, so instances cannot be allocated or read directly. */
     opaque: boolean;
+    /** Whether the record is exposed to language bindings. */
     introspectable: boolean;
+    /** Struct members: the named fields first, then the anonymous inline unions, then the inline records. */
     fields: GirField[];
+    /** Functions taking an instance of the record as their first argument. */
     methods: GirFunction[];
+    /** Functions returning a new instance of the record. */
     constructors: GirFunction[];
+    /** Functions scoped to the record but taking no instance. */
     functions: GirFunction[];
+    /** Whether the record is a union, so its fields overlap instead of following one another. */
     isUnion: boolean;
 };
 
@@ -31,8 +53,8 @@ const recordFromNode = (
     context: ParseContext,
 ): GirRecord => ({
     isVtable,
+    ...documentedFromNode(node),
     name: attr(node, "name") ?? attr(node, "glib:name") ?? "",
-    doc: getDoc(node),
     cType: attr(node, "c:type"),
     glibTypeName: attr(node, "glib:type-name"),
     glibGetType: attr(node, "glib:get-type"),

package/src/gir/size.ts

@@ -11,6 +11,11 @@ type FieldSlot = {
     bitWidth: number | undefined;
 };
 
+type FieldSlots = {
+    slots: FieldSlot[];
+    size: number;
+};
+
 type FieldLayoutInput = {
     layout: FieldLayout;
     bits: number | undefined;
@@ -39,7 +44,7 @@ const roundUp = (value: number, multiple: number): number => {
     return remainder === 0 ? value : value + (multiple - remainder);
 };
 
-const computeUnionSlots = (fields: FieldLayoutInput[]): { slots: FieldSlot[]; size: number } => {
+const computeUnionSlots = (fields: FieldLayoutInput[]): FieldSlots => {
     let maxSize = 0;
     let maxAlign = 1;
 
@@ -95,7 +100,7 @@ const processStructField = (state: StructLayoutState, slots: FieldSlot[], field:
     pushBitfield({ state, slots, field, align, bits: field.bits });
 };
 
-const computeStructSlots = (fields: FieldLayoutInput[]): { slots: FieldSlot[]; size: number } => {
+const computeStructSlots = (fields: FieldLayoutInput[]): FieldSlots => {
     const slots: FieldSlot[] = [];
     const state: StructLayoutState = { bitCursor: 0, maxAlign: 1 };
 
@@ -106,7 +111,7 @@ const computeStructSlots = (fields: FieldLayoutInput[]): { slots: FieldSlot[]; s
     return { slots, size: roundUp(roundUp(state.bitCursor, 8) / 8, state.maxAlign) };
 };
 
-const computeFieldSlots = (fields: FieldLayoutInput[], isUnion = false): { slots: FieldSlot[]; size: number } =>
+const computeFieldSlots = (fields: FieldLayoutInput[], isUnion = false): FieldSlots =>
     isUnion ? computeUnionSlots(fields) : computeStructSlots(fields);
 
 export { layoutOfPrimitive, computeFieldSlots, type FieldLayout, type FieldSlot, type FieldLayoutInput };