@gtkx/codegen 1.0.0-rc.4 → 1.0.0

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,23 +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 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),
@@ -25,12 +41,11 @@ const fieldFromNode = (node: RawNode, context: ParseContext): GirField => ({
     private: isAttrTrue(node, "private", false),
     bits: intAttr(node, "bits"),
     inlineMembers: undefined,
-    inlineIsUnion: false,
+    isInlineUnion: false,
 });
 
 const anonymousMemberFromNode = (node: RawNode, isUnion: boolean, context: ParseContext): GirField => ({
-    name: nameAttr(node),
-    doc: getDoc(node),
+    ...documentedFromNode(node),
     type: undefined,
     cType: undefined,
     readable: false,
@@ -38,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[] => [
@@ -47,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/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;
@@ -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"),

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,75 @@ 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";
 
+/** 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;
 };
 
+/** 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 +101,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),
@@ -86,11 +130,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 +147,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"),