@gtkx/codegen 1.0.0-rc.3 → 1.0.0

package/src/gir/annotations.ts

@@ -0,0 +1,37 @@
+import { attr, getDoc, getDocDeprecated, isAttrTrue, nameAttr, type RawNode } from "./parse.js";
+
+/** Release and deprecation annotations GIR carries on a documentable element. */
+type GirAnnotations = {
+    /** Library release the symbol appeared in, from the `version` attribute. */
+    since: string | undefined;
+    /** Whether GIR marks the symbol deprecated. */
+    isDeprecated: boolean;
+    /** Release the symbol was deprecated in, from the `deprecated-version` attribute. */
+    deprecatedSince: string | undefined;
+    /** Prose from `<doc-deprecated>` naming what to use instead. */
+    deprecationDoc: string | undefined;
+};
+
+type DocumentedNode = {
+    name: string;
+    doc: string | undefined;
+    annotations: GirAnnotations;
+};
+
+const annotationsFromNode = (node: RawNode | undefined): GirAnnotations => ({
+    since: attr(node, "version"),
+    isDeprecated: isAttrTrue(node, "deprecated"),
+    deprecatedSince: attr(node, "deprecated-version"),
+    deprecationDoc: getDocDeprecated(node),
+});
+
+const documentedFromNode = (node: RawNode): DocumentedNode => ({
+    name: nameAttr(node),
+    doc: getDoc(node),
+    annotations: annotationsFromNode(node),
+});
+
+const hasAnnotations = (annotations: GirAnnotations): boolean =>
+    annotations.since !== undefined || annotations.isDeprecated || annotations.deprecatedSince !== undefined;
+
+export { annotationsFromNode, documentedFromNode, hasAnnotations, type GirAnnotations };

package/src/gir/callback.ts

@@ -3,6 +3,7 @@ import type { RawNode } from "./parse.js";
 import type { ParseContext } from "./type-id.js";
 import { type GirCallable, parseCallable } from "./parameter.js";
 
+/** The signature of a function pointer type GIR declares, whether named or anonymous. */
 type GirCallback = GirCallable;
 
 const callbackFromNode = (node: RawNode, context: ParseContext): GirCallback => parseCallable(node, context);
@@ -10,6 +11,7 @@ const callbackFromNode = (node: RawNode, context: ParseContext): GirCallback =>
 const callbackAsFunction = (callback: GirCallback): GirFunction => ({
     name: callback.name,
     doc: callback.doc,
+    annotations: callback.annotations,
     cIdentifier: undefined,
     movedTo: undefined,
     throws: callback.throws,

package/src/gir/class.ts

@@ -1,35 +1,72 @@
 import type { ParseContext } from "./type-id.js";
+import { documentedFromNode, type GirAnnotations } from "./annotations.js";
 import { functionFromNode, type GirFunction } from "./function.js";
 import { type GirCallable, parseCallable } from "./parameter.js";
-import { attr, getChildren, getDoc, GIR_CONSTRUCTOR_TAG, isAttrTrue, nameAttr, type RawNode } from "./parse.js";
+import { attr, getChildren, GIR_CONSTRUCTOR_TAG, isAttrTrue, type RawNode } from "./parse.js";
 import { type GirProperty, propertyFromNode } from "./property.js";
 
+/** A `<virtual-method>` on a class or interface: the vtable slot's own documentation and signature. */
+type GirVirtualMethod = GirCallable & {
+    /** Method GIR names as invoking this slot, absent when the slot has no invoker. */
+    invoker: string | undefined;
+};
+
+/** A `<class>` or `<interface>` declared by a GIR namespace. */
 type GirClass = {
+    /** Name GIR gives the type, without its namespace prefix. */
     name: string;
+    /** Documentation GIR carries for the type. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the type. */
+    annotations: GirAnnotations;
+    /** C type of an instance, such as `GtkWidget`. */
     cType: string | undefined;
+    /** The class it derives from, qualified when it lives in another namespace. */
     parent: string | undefined;
+    /** GType name the type registers under, such as `GtkWidget`. */
     glibTypeName: string | undefined;
+    /** C function returning the GType, such as `gtk_widget_get_type`. */
     glibGetType: string | undefined;
+    /** Record holding the class or interface vtable, which virtual method bindings are laid out against. */
     glibTypeStruct: string | undefined;
+    /** C function that takes a reference, on a type that manages its own refcount. */
     glibRefFunc: string | undefined;
+    /** C function that drops a reference, on a type that manages its own refcount. */
     glibUnrefFunc: string | undefined;
+    /** Whether the type is its own GType fundamental rather than a GObject descendant. */
     fundamental: boolean;
+    /** Whether the class cannot be instantiated on its own. */
     isAbstract: boolean;
+    /** Whether the type came from an `<interface>` rather than a `<class>`. */
     isInterface: boolean;
+    /** Whether GIR exposes the type to bindings; codegen skips it when false. */
     introspectable: boolean;
+    /** Interfaces the class implements. */
     implements: string[];
+    /** Types an implementer of this interface must also provide. */
     prerequisites: string[];
+    /** Methods taking an instance. */
     methods: GirFunction[];
+    /** Functions returning a new instance. */
     constructors: GirFunction[];
+    /** Functions namespaced under the type that take no instance. */
     functions: GirFunction[];
+    /** GObject properties the type declares. */
     properties: GirProperty[];
+    /** GObject signals the type declares. */
     signals: GirCallable[];
+    /** Virtual methods the type declares, carrying the documentation their vtable slots are generated from. */
+    vfuncs: GirVirtualMethod[];
 };
 
+const virtualMethodsFromNode = (node: RawNode, context: ParseContext): GirVirtualMethod[] =>
+    getChildren(node, "virtual-method").map((vfunc) => ({
+        ...parseCallable(vfunc, context),
+        invoker: attr(vfunc, "invoker"),
+    }));
+
 const classFromNode = (node: RawNode, isInterface: boolean, context: ParseContext): GirClass => ({
-    name: nameAttr(node),
-    doc: getDoc(node),
+    ...documentedFromNode(node),
     cType: attr(node, "c:type"),
     parent: attr(node, "parent"),
     glibTypeName: attr(node, "glib:type-name"),
@@ -52,6 +89,7 @@ const classFromNode = (node: RawNode, isInterface: boolean, context: ParseContex
     functions: getChildren(node, "function").map((fn) => functionFromNode(fn, context)),
     properties: getChildren(node, "property").map((property) => propertyFromNode(property, context)),
     signals: getChildren(node, "glib:signal").map((signal) => parseCallable(signal, context)),
+    vfuncs: virtualMethodsFromNode(node, context),
 });
 
-export { classFromNode, type GirClass };
+export { classFromNode, type GirClass, type GirVirtualMethod };

package/src/gir/enum.ts

@@ -1,39 +1,59 @@
-import { attr, getChildren, getDoc, isAttrTrue, nameAttr, type RawNode } from "./parse.js";
+import { documentedFromNode, type GirAnnotations } from "./annotations.js";
+import { attr, getChildren, isAttrTrue, type RawNode } from "./parse.js";
 
+/** One member of a {@link GirEnum}. */
 type EnumMember = {
+    /** The member's GIR name, which the emitted key is derived from. */
     name: string;
+    /** Documentation prose from GIR, emitted as the member's JSDoc. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the member. */
+    annotations: GirAnnotations;
+    /** The member's numeric value, `0` when GIR declares none. */
     value: string;
+    /** C constant the member is exposed as, such as `GTK_ORIENTATION_HORIZONTAL`. */
     cIdentifier: string | undefined;
 };
 
+/** Whether an enum is a plain enumeration or a bitfield of flags. */
 type EnumKind = "enumeration" | "bitfield";
 
+/** An enumeration or bitfield declared by a GIR namespace. */
 type GirEnum = {
+    /** Whether the declaration is a plain enumeration or a bitfield. */
     kind: EnumKind;
+    /** Name the enum is exported under, without its namespace prefix. */
     name: string;
+    /** Documentation prose from GIR, emitted as the enum's JSDoc. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the enum. */
+    annotations: GirAnnotations;
+    /** GType name of the enum, absent when it is not registered with GLib. */
     glibTypeName: string | undefined;
+    /** C function returning the enum's GType, absent when it is not registered with GLib. */
     glibGetType: string | undefined;
+    /** Quark name of the GError domain the members are codes of, absent on enums that carry no domain. */
     errorDomain: string | undefined;
+    /** Whether the enum is introspectable; code generation skips the ones that are not. */
     introspectable: boolean;
+    /** The enum's members, in declaration order. */
     members: EnumMember[];
 };
 
+const enumMemberFromNode = (node: RawNode): EnumMember => ({
+    ...documentedFromNode(node),
+    value: attr(node, "value") ?? "0",
+    cIdentifier: attr(node, "c:identifier"),
+});
+
 const enumFromNode = (node: RawNode, kind: EnumKind): GirEnum => ({
     kind,
-    name: nameAttr(node),
-    doc: getDoc(node),
+    ...documentedFromNode(node),
     glibTypeName: attr(node, "glib:type-name"),
     glibGetType: attr(node, "glib:get-type"),
     errorDomain: attr(node, "glib:error-domain"),
     introspectable: isAttrTrue(node, "introspectable", true),
-    members: getChildren(node, "member").map((member) => ({
-        name: nameAttr(member),
-        doc: getDoc(member),
-        value: attr(member, "value") ?? "0",
-        cIdentifier: attr(member, "c:identifier"),
-    })),
+    members: getChildren(node, "member").map((member) => enumMemberFromNode(member)),
 });
 
-export { enumFromNode, type GirEnum };
+export { enumFromNode, type EnumMember, type GirEnum };

package/src/gir/field.ts

@@ -1,24 +1,39 @@
 import type { ParseContext, TypeId } from "./type-id.js";
-import { attr, getChild, getChildren, getDoc, intAttr, isAttrTrue, nameAttr, type RawNode } from "./parse.js";
+import { documentedFromNode, type GirAnnotations } from "./annotations.js";
+import { attr, getChild, getChildren, intAttr, isAttrTrue, type RawNode } from "./parse.js";
 import { typeRefFromNode } from "./type-ref.js";
 
+/**
+ * One slot in a record or union layout: a named field, or a nested struct or union
+ * whose own members are laid out inline.
+ */
 type GirField = {
+    /** Field name as GIR spells it. */
     name: string;
+    /** Documentation prose from GIR, emitted as the field accessor's JSDoc. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the field. */
+    annotations: GirAnnotations;
+    /** The field's value type, absent for a nested struct or union and for one GIR leaves undeclared. */
     type: TypeId | undefined;
+    /** The C type spelled on the field, which decides whether it is read through a pointer. */
     cType: string | undefined;
+    /** Whether the field can be read; one that is neither readable nor writable gets no accessor at all. */
     readable: boolean;
+    /** Whether the field can be written, which is what earns it a setter alongside its getter. */
     writable: boolean;
+    /** Whether the field is private to the library, as every nested struct or union is. */
     private: boolean;
+    /** Width in bits when the field is a C bitfield member. */
     bits: number | undefined;
-    /** Members of an anonymous nested `<union>`/`<record>`, which occupies a slot but has no type. */
+    /** Members of a nested struct or union, absent for a named field. */
     inlineMembers: GirField[] | undefined;
-    inlineIsUnion: boolean;
+    /** Whether {@link GirField.inlineMembers} overlap as a union rather than following one another as a struct. */
+    isInlineUnion: boolean;
 };
 
 const fieldFromNode = (node: RawNode, context: ParseContext): GirField => ({
-    name: nameAttr(node),
-    doc: getDoc(node),
+    ...documentedFromNode(node),
     type: typeRefFromNode(node, context),
     cType: attr(getChild(node, "type"), "c:type"),
     readable: isAttrTrue(node, "readable", true),
@@ -26,15 +41,11 @@ const fieldFromNode = (node: RawNode, context: ParseContext): GirField => ({
     private: isAttrTrue(node, "private", false),
     bits: intAttr(node, "bits"),
     inlineMembers: undefined,
-    inlineIsUnion: false,
+    isInlineUnion: false,
 });
 
-// A record may embed an anonymous `<union>` or `<record>` instead of naming a type for it. The
-// member occupies a real slot and contributes its own size and alignment, but carries no `<type>`,
-// so it has to be admitted as a field whose layout comes from its own children.
 const anonymousMemberFromNode = (node: RawNode, isUnion: boolean, context: ParseContext): GirField => ({
-    name: nameAttr(node),
-    doc: getDoc(node),
+    ...documentedFromNode(node),
     type: undefined,
     cType: undefined,
     readable: false,
@@ -42,7 +53,7 @@ const anonymousMemberFromNode = (node: RawNode, isUnion: boolean, context: Parse
     private: true,
     bits: undefined,
     inlineMembers: collectFields(node, context),
-    inlineIsUnion: isUnion,
+    isInlineUnion: isUnion,
 });
 
 const collectFields = (node: RawNode, context: ParseContext): GirField[] => [
@@ -51,4 +62,4 @@ const collectFields = (node: RawNode, context: ParseContext): GirField[] => [
     ...getChildren(node, "record").map((member) => anonymousMemberFromNode(member, false, context)),
 ];
 
-export { collectFields, fieldFromNode, type GirField };
+export { collectFields, type GirField };

package/src/gir/function.ts

@@ -1,19 +1,34 @@
+import type { GirAnnotations } from "./annotations.js";
 import type { ParseContext } from "./type-id.js";
 import { PARAMETERS_MISSING_NULLABLE_ANNOTATION } from "./nullable-overrides.js";
 import { type GirParameter, type GirReturnValue, parameterFromNode, parseCallable } from "./parameter.js";
 import { attr, getChild, type RawNode } from "./parse.js";
 
+/** A callable declared by a GIR namespace, class, or record: a function, a method, or a constructor. */
 type GirFunction = {
+    /** Local name within its owner, taken from the `shadows` annotation when the callable has one. */
     name: string;
+    /** Documentation text carried by the GIR node. */
     doc: string | undefined;
+    /** Release and deprecation annotations GIR carries on the callable. */
+    annotations: GirAnnotations;
+    /** C symbol the callable is invoked through. */
     cIdentifier: string | undefined;
+    /** Whether the C function takes a trailing `GError` out parameter and can fail. */
     throws: boolean;
+    /** Whether the GIR marks the callable as introspectable, and so bindable. */
     introspectable: boolean;
+    /** Qualified `Type.member` the GIR redirects the callable to, from its `moved-to` annotation. */
     movedTo: string | undefined;
+    /** Name of the callable that shadows this one, from the GIR's `shadowed-by` annotation. */
     shadowedBy: string | undefined;
+    /** Name of the callable that completes this asynchronous one, from the GIR's `glib:finish-func`. */
     finishFunc: string | undefined;
+    /** The instance the callable is invoked on, absent for constructors and namespace-level functions. */
     instance: GirParameter | undefined;
+    /** Parameters other than the instance one, in declaration order. */
     parameters: GirParameter[];
+    /** What the callable returns, with its transfer and nullability. */
     returnValue: GirReturnValue;
 };
 

package/src/gir/gir-path.ts

@@ -4,6 +4,13 @@ import { existsSync } from "node:fs";
 
 const SYSTEM_GIR_PATH = "/usr/share/gir-1.0";
 
+/**
+ * The directories to search for `.gir` files, in precedence order: the config's own `girPath`, then
+ * `GTKX_GIR_PATH`, then `/usr/share/gir-1.0`, then the girdir pkg-config reports for
+ * gobject-introspection-1.0. Duplicates are dropped, and the last two are included only when they exist.
+ *
+ * @throws If pkg-config is installed but fails while being queried.
+ */
 const resolveGirPath = (configGirPath: string[] | undefined): string[] => {
     const paths: string[] = [];
 

package/src/gir/libraries.ts

@@ -1,14 +1,31 @@
 import { sortStrings } from "@gtkx/utils";
 import { readdirSync } from "node:fs";
 
-type GirNamespace = { name: string; version: string; identifier: string };
-type LibrarySelection = typeof LIBRARIES_WILDCARD | string[] | undefined;
+/** 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 = "*" | string[] | undefined;
 
 const LIBRARIES_WILDCARD = "*";
 const GIR_LIBRARY_PATTERN = /^[A-Za-z][A-Za-z0-9]*-\d+(?:\.\d+)*$/;
 const DEFAULT_LIBRARIES: string[] = ["Gtk-4.0"];
 const GIR_FILE_SUFFIX = ".gir";
 
+/**
+ * Expands a `libraries` config value into the GIR identifiers to generate from: `"Gtk-4.0"` alone when
+ * nothing is configured, everything installed for `"*"`, and otherwise the given list with `"Gtk-4.0"`
+ * prepended unless it already names a Gtk version.
+ *
+ * @throws If `"*"` matched no `.gir` file anywhere on the GIR path.
+ */
 const resolveLibraries = (libraries: LibrarySelection, girPath: string[]): string[] => {
     if (libraries === undefined) {
         return [...DEFAULT_LIBRARIES];
@@ -74,6 +91,10 @@ const collectDirNamespaces = (highestByName: Map<string, GirNamespace>, dir: str
     }
 };
 
+/**
+ * Every GIR library installed on the search path, as sorted `Name-Version` identifiers. A namespace found
+ * in more than one version contributes only its highest, and unreadable directories are skipped.
+ */
 const discoverGirNamespaces = (girPath: string[]): string[] => {
     const highestByName: Map<string, GirNamespace> = new Map();
 

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;
@@ -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,52 +1,90 @@
 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;
+    /** 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;
+    /** 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;
 };
 
@@ -97,15 +135,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"),