@gtkx/codegen 1.0.0-rc.3 → 1.0.0

package/src/store/gi/method.ts

@@ -14,16 +14,28 @@ import {
     emittedArgIndices,
     foldedLengthIndices,
     foldOutParamShape,
+    type InputParameter,
     inputParameters,
     parameterIdentifier,
 } from "../../analysis/param-structure.js";
 import { renderTsType } from "../../analysis/ts-type.js";
 import { type GirParameter, isCallerAllocatedOut, isInoutParameter, isOutParameter } from "../../gir/parameter.js";
 import { hasUnknownArrayLength, type TypeId } from "../../gir/type-id.js";
+import { areClosuresInvoked } from "./closure-invocation.js";
 import { itemComparatorArgDescriptors, itemComparatorTsType } from "./item-comparators.js";
-import { isCollectibleCallerOut, isHandlePassedInPlace, isHandlePassing } from "./param-marshal.js";
+import { isClosureType, isCollectibleCallerOut, isHandlePassedInPlace, isHandlePassing } from "./param-marshal.js";
 
-type PromisifiedStep = { sawOptional: boolean; expression: string | undefined };
+type PromisifiedStep = { hasSeenOptional: boolean; expression: string | undefined };
+
+type InputParameterOptions = {
+    shouldSkip: (parameter: GirParameter) => boolean;
+    isOptionalExtra: (parameter: GirParameter) => boolean;
+};
+
+type CallExpressionOptions = {
+    fn: GirFunction;
+    isForcedNullable?: boolean | undefined;
+};
 
 type PromisifyContext = {
     context: ModuleContext;
@@ -44,8 +56,8 @@ type CallArgPlan = {
 
 type ParamDescriptorOptions = {
     direction?: "out" | "inout";
-    callerAllocated?: boolean;
-    consumed?: boolean;
+    isCallerAllocated?: boolean;
+    isConsumed?: boolean;
 };
 
 type ArgIndexOptions = {
@@ -71,15 +83,34 @@ const arrayLengthArgument = (source: GirParameter, sourceIndex: number): string
 };
 
 const renderMethodSignature = (context: ModuleContext, fn: GirFunction): string =>
-    renderInputParameters(
-        context,
-        fn,
-        () => false,
-        () => false,
-    );
+    renderInputParameters(context, fn, {
+        shouldSkip: () => false,
+        isOptionalExtra: () => false,
+    });
+
+const closureAnnotation = (context: ModuleContext, base: string): string => {
+    context.addRuntimeTypeImport("ClosureCallback");
+
+    return `${base} | ClosureCallback`;
+};
 
-const parameterAnnotation = (context: ModuleContext, fn: GirFunction, parameter: GirParameter): string =>
-    itemComparatorTsType(context, fn, parameter) ?? renderTsType(context, parameter.type, parameter.nullable);
+const requiresClosureMarshal = (context: ModuleContext, fn: GirFunction, ref: TypeId): boolean =>
+    isClosureType(context, ref) && areClosuresInvoked(fn);
+
+const requiresClosureAnnotation = (context: ModuleContext, fn: GirFunction, parameter: GirParameter): boolean =>
+    parameter.type !== undefined && requiresClosureMarshal(context, fn, parameter.type);
+
+const parameterAnnotation = (context: ModuleContext, fn: GirFunction, parameter: GirParameter): string => {
+    const comparator = itemComparatorTsType(context, fn, parameter);
+
+    if (comparator !== undefined) {
+        return comparator;
+    }
+
+    const base = renderTsType(context, parameter.type, parameter.nullable);
+
+    return requiresClosureAnnotation(context, fn, parameter) ? closureAnnotation(context, base) : base;
+};
 
 const isParameterOptional = (parameter: GirParameter, isOptionalExtra: (parameter: GirParameter) => boolean): boolean =>
     parameter.optional || isOptionalExtra(parameter);
@@ -87,27 +118,23 @@ const isParameterOptional = (parameter: GirParameter, isOptionalExtra: (paramete
 const formatParameterPart = (name: string, annotation: string, isOptional: boolean): string =>
     isOptional ? `${name}?: ${annotation}` : `${name}: ${annotation}`;
 
-const renderInputParameters = (
-    context: ModuleContext,
-    fn: GirFunction,
-    shouldSkip: (parameter: GirParameter) => boolean,
-    isOptionalExtra: (parameter: GirParameter) => boolean,
-): string => {
+const renderInputParameters = (context: ModuleContext, fn: GirFunction, options: InputParameterOptions): string => {
     const parts: string[] = [];
-    let isSawOptional = false;
+    let hasSeenOptional = false;
 
     for (const { parameter, index } of inputParameters(context.library, fn)) {
-        if (shouldSkip(parameter)) {
+        if (options.shouldSkip(parameter)) {
             continue;
         }
 
         const name = parameterIdentifier(parameter, index);
 
-        if (isParameterOptional(parameter, isOptionalExtra)) {
-            isSawOptional = true;
+        if (isParameterOptional(parameter, options.isOptionalExtra)) {
+            hasSeenOptional = true;
         }
 
-        parts.push(formatParameterPart(name, parameterAnnotation(context, fn, parameter), isSawOptional));
+        const annotation = parameterAnnotation(context, fn, parameter);
+        parts.push(formatParameterPart(name, annotation, hasSeenOptional));
     }
 
     return parts.join(", ");
@@ -118,9 +145,21 @@ const isReturnedOutParameter = (context: ModuleContext, parameter: GirParameter)
     (isCallerAllocatedOut(parameter) && isCollectibleCallerOut(context, parameter)) ||
     isInoutParameter(parameter);
 
-const renderMethodReturnType = (context: ModuleContext, fn: GirFunction): string => {
+const returnedOutParameters = (context: ModuleContext, fn: GirFunction): InputParameter[] => {
     const folded = foldedLengthIndices(context.library, fn);
-    const outs = fn.parameters.filter((p, index) => isReturnedOutParameter(context, p) && !folded.has(index));
+    const result: InputParameter[] = [];
+
+    for (const [index, parameter] of fn.parameters.entries()) {
+        if (isReturnedOutParameter(context, parameter) && !folded.has(index)) {
+            result.push({ parameter, index });
+        }
+    }
+
+    return result;
+};
+
+const renderMethodReturnType = (context: ModuleContext, fn: GirFunction): string => {
+    const outs = returnedOutParameters(context, fn);
 
     const primary = shouldOmitPrimaryReturn(context.library, fn.returnValue)
         ? undefined
@@ -130,7 +169,7 @@ const renderMethodReturnType = (context: ModuleContext, fn: GirFunction): string
         return primary ?? "void";
     }
 
-    const outTypes = outs.map((parameter) => renderTsType(context, parameter.type, parameter.nullable));
+    const outTypes = outs.map(({ parameter }) => renderTsType(context, parameter.type, parameter.nullable));
 
     return foldOutParamShape(primary, outTypes);
 };
@@ -139,36 +178,36 @@ const classifyPromisifiedParameter = (
     promisify: PromisifyContext,
     parameter: GirParameter,
     index: number,
-    state: { cancellableIndex: number; sawOptional: boolean },
+    state: { cancellableIndex: number; hasSeenOptional: boolean },
 ): PromisifiedStep => {
     if (parameter.isVarargs) {
-        return { sawOptional: state.sawOptional, expression: undefined };
+        return { hasSeenOptional: state.hasSeenOptional, expression: undefined };
     }
 
     if (index === state.cancellableIndex) {
-        return { sawOptional: true, expression: undefined };
+        return { hasSeenOptional: true, expression: undefined };
     }
 
     if (shouldSkipPromisifiedParameter(promisify, parameter, index)) {
-        return { sawOptional: state.sawOptional, expression: undefined };
+        return { hasSeenOptional: state.hasSeenOptional, expression: undefined };
     }
 
-    const isSawOptional = state.sawOptional || parameter.optional;
+    const hasSeenOptional = state.hasSeenOptional || parameter.optional;
 
-    return { sawOptional: isSawOptional, expression: promisifiedArgument(promisify, parameter, index, isSawOptional) };
+    return { hasSeenOptional, expression: promisifiedArgument(promisify, parameter, index, hasSeenOptional) };
 };
 
 const collectPromisifiedArguments = (promisify: PromisifyContext, cancellableIndex: number): string[] => {
     const expressions: string[] = [];
-    let isSawOptional = false;
+    let hasSeenOptional = false;
 
     for (const [index, parameter] of promisify.asyncFn.parameters.entries()) {
         const step = classifyPromisifiedParameter(promisify, parameter, index, {
             cancellableIndex,
-            sawOptional: isSawOptional,
+            hasSeenOptional,
         });
 
-        isSawOptional = step.sawOptional;
+        hasSeenOptional = step.hasSeenOptional;
 
         if (step.expression !== undefined) {
             expressions.push(step.expression);
@@ -242,7 +281,7 @@ const promisifiedArgument = (
         return arrayLengthArgument(source, sourceIndex);
     }
 
-    return parameterCallExpression(context, parameter, index, hasSeenOptional);
+    return parameterCallExpression(context, parameter, index, { fn: asyncFn, isForcedNullable: hasSeenOptional });
 };
 
 const findCancellableIndex = (context: ModuleContext, parameters: GirParameter[]): number =>
@@ -253,12 +292,10 @@ const renderPromisifiedSignature = (
     asyncFn: GirFunction,
     finishFn: GirFunction,
 ): { signature: string; returnType: string } => {
-    const signature = renderInputParameters(
-        context,
-        asyncFn,
-        (parameter) => isCallbackParameter(context, parameter),
-        (parameter) => isCancellable(context, parameter),
-    );
+    const signature = renderInputParameters(context, asyncFn, {
+        shouldSkip: (parameter) => isCallbackParameter(context, parameter),
+        isOptionalExtra: (parameter) => isCancellable(context, parameter),
+    });
 
     const finishReturn = renderMethodReturnType(context, finishFn);
 
@@ -298,12 +335,12 @@ const paramDescriptorLiteral = (descriptor: string, options: ParamDescriptorOpti
         parts.push(`direction: ${sourceStringLiteral(options.direction)}`);
     }
 
-    if (options.callerAllocated === true) {
-        parts.push("callerAllocated: true");
+    if (options.isCallerAllocated === true) {
+        parts.push("isCallerAllocated: true");
     }
 
-    if (options.consumed === true) {
-        parts.push("consumed: true");
+    if (options.isConsumed === true) {
+        parts.push("isConsumed: true");
     }
 
     return `{ ${parts.join(", ")} }`;
@@ -405,9 +442,10 @@ const planInoutArgument = (
             : undefined;
 
     return planInoutParam(context, parameter, {
+        fn,
         index,
         argIndex: planContext.argIndex,
-        consumed: folded.has(index),
+        isConsumed: folded.has(index),
         lengthSource,
     });
 };
@@ -433,10 +471,13 @@ const planOutParam = (
     argIndex: ArgIndexOptions,
     isConsumed: boolean,
 ): CallArgPlan => {
-    const descriptor = renderDescriptor(context, parameter.type, parameter.transferOwnership, argIndex);
+    const descriptor = renderDescriptor(context, parameter.type, parameter.transferOwnership, {
+        ...argIndex,
+        hasOutIndirection: true,
+    });
 
     return {
-        paramLiteral: paramDescriptorLiteral(descriptor, { direction: "out", consumed: isConsumed }),
+        paramLiteral: paramDescriptorLiteral(descriptor, { direction: "out", isConsumed }),
         inputExpr: undefined,
     };
 };
@@ -474,7 +515,7 @@ const planCallerOut = (
         const classExpression = context.qualify(name.namespaceName, name.typeName);
 
         return {
-            paramLiteral: paramDescriptorLiteral(descriptor, { direction: "out", callerAllocated: true }),
+            paramLiteral: paramDescriptorLiteral(descriptor, { direction: "out", isCallerAllocated: true }),
             inputExpr: `new ${classExpression}()`,
         };
     }
@@ -486,30 +527,38 @@ const planInoutParam = (
     context: ModuleContext,
     parameter: GirParameter,
     options: {
+        fn: GirFunction;
         index: number;
         argIndex: ArgIndexOptions;
-        consumed: boolean;
+        isConsumed: boolean;
         lengthSource?: { source: GirParameter; index: number } | undefined;
     },
 ): CallArgPlan => {
-    const { index, argIndex, consumed, lengthSource } = options;
+    const { fn, index, argIndex, isConsumed, lengthSource } = options;
 
     if (isHandlePassedInPlace(context, parameter)) {
         const descriptor = renderDescriptor(context, parameter.type, "none", argIndex);
 
         return {
-            paramLiteral: paramDescriptorLiteral(descriptor, { direction: "inout", callerAllocated: true, consumed }),
+            paramLiteral: paramDescriptorLiteral(descriptor, {
+                direction: "inout",
+                isCallerAllocated: true,
+                isConsumed,
+            }),
             inputExpr: parameterIdentifier(parameter, index),
         };
     }
 
-    const descriptor = renderDescriptor(context, parameter.type, parameter.transferOwnership, argIndex);
+    const descriptor = renderDescriptor(context, parameter.type, parameter.transferOwnership, {
+        ...argIndex,
+        hasOutIndirection: true,
+    });
 
     return {
-        paramLiteral: paramDescriptorLiteral(descriptor, { direction: "inout", consumed }),
+        paramLiteral: paramDescriptorLiteral(descriptor, { direction: "inout", isConsumed }),
         inputExpr:
             lengthSource === undefined
-                ? parameterCallExpression(context, parameter, index)
+                ? parameterCallExpression(context, parameter, index, { fn })
                 : arrayLengthArgument(lengthSource.source, lengthSource.index),
     };
 };
@@ -540,27 +589,30 @@ const planInParam = (
 
     return {
         paramLiteral: paramDescriptorLiteral(descriptor, {}),
-        inputExpr: parameterCallExpression(context, parameter, index),
+        inputExpr: parameterCallExpression(context, parameter, index, { fn }),
     };
 };
 
+const nullableHandleExpression = (name: string): string => `${name} == null ? null : getHandle(${name})`;
+
 const handleArgument = (context: ModuleContext, name: string, isNullable: boolean): string => {
-    if (isNullable) {
-        context.addRuntimeImport("tryGetHandle");
+    context.addRuntimeImport("getHandle");
 
-        return `tryGetHandle(${name})`;
-    }
+    return isNullable ? nullableHandleExpression(name) : `getHandle(${name})`;
+};
 
-    context.addRuntimeImport("getHandle");
+const closureArgument = (context: ModuleContext, name: string, isNullable: boolean): string => {
+    const helper = isNullable ? "tryToClosure" : "toClosure";
+    context.addRuntimeImport(helper);
 
-    return `getHandle(${name})`;
+    return `${helper}(${name})`;
 };
 
 const hashtableArgument = (context: ModuleContext, valueRef: TypeId, name: string): string => {
     if (isHandlePassing(context, valueRef)) {
-        context.addRuntimeImport("tryGetHandle");
+        context.addRuntimeImport("getHandle");
 
-        return `${name} ? globalThis.Array.from(${name}).map(([k, v]) => [k, tryGetHandle(v)]) : null`;
+        return `${name} ? globalThis.Array.from(${name}).map(([k, v]) => [k, ${nullableHandleExpression("v")}]) : null`;
     }
 
     return `${name} ? globalThis.Array.from(${name}) : null`;
@@ -588,8 +640,6 @@ const collectionArgument = (
     return mapHandleExpression(name, isNullable);
 };
 
-// An array whose length nothing states is marshalled as the bare pointer it is, so there is nothing
-// to map over.
 const isMappableSequence = (context: ModuleContext, type: GirType | undefined): boolean => {
     if (type?.kind === "carray") {
         return !hasUnknownArrayLength(type) && isHandlePassing(context, type.element);
@@ -602,8 +652,9 @@ const parameterCallExpression = (
     context: ModuleContext,
     parameter: GirParameter,
     index: number,
-    isForcedNullable = false,
+    options: CallExpressionOptions,
 ): string => {
+    const { fn, isForcedNullable = false } = options;
     const name = parameterIdentifier(parameter, index);
     const ref = parameter.type;
 
@@ -613,6 +664,10 @@ const parameterCallExpression = (
 
     const isNullable = parameter.nullable || parameter.optional || isForcedNullable;
 
+    if (requiresClosureMarshal(context, fn, ref)) {
+        return closureArgument(context, name, isNullable);
+    }
+
     if (isHandlePassing(context, ref)) {
         return handleArgument(context, name, isNullable);
     }
@@ -623,9 +678,12 @@ const parameterCallExpression = (
 };
 
 export {
+    constructibleName,
+    isCallbackParameter,
     methodExportName,
     renderMethodSignature,
     renderMethodReturnType,
+    returnedOutParameters,
     renderPromisifiedBody,
     finishCallExpression,
     renderPromisifiedSignature,

package/src/store/gi/param-marshal.ts

@@ -68,4 +68,18 @@ const isHandlePassing = (context: ModuleContext, ref: TypeId): boolean => {
     }
 };
 
-export { isHandlePassedInPlace, isCollectibleCallerOut, isRecordCallerOut, isRecordInout, isHandlePassing };
+const isClosureType = (context: ModuleContext, ref: TypeId): boolean => {
+    const name = context.library.nameFor(ref);
+
+    return name?.namespaceName === "GObject" && name.typeName === "Closure";
+};
+
+export {
+    isClosureType,
+    isHandlePassedInPlace,
+    isCollectibleCallerOut,
+    isRecordCallerOut,
+    isRecordInout,
+    isHandlePassing,
+    underlyingType,
+};

package/src/store/gi/pipeline.ts

@@ -5,10 +5,10 @@ import { renderTsType } from "../../analysis/ts-type.js";
 import { PRIMITIVE_TS_TYPE, primitiveCategory } from "../../gir/primitives.js";
 import { splitOptionalNamespace } from "../../gir/type-ref.js";
 import { ModuleContext } from "../../writer/context.js";
-import { renderJsDoc } from "../../writer/doc.js";
 import { generateCallback } from "./callback.js";
 import { generateClass } from "./class.js";
 import { generateConstant } from "./constant.js";
+import { getDoc } from "./doc-spec.js";
 import { generateEnum } from "./enum.js";
 import { generateNamespaceBootstrap, generateNamespaceFunction } from "./function.js";
 import { generateInterface } from "./interface.js";
@@ -72,7 +72,12 @@ const generateNamespaceMembers = (context: ModuleContext, namespace: GirNamespac
 const generateAlias = (context: ModuleContext, alias: GirAlias): void => {
     const category = alias.cType === undefined ? undefined : primitiveCategory(alias.cType);
     const targetType = category === "gtype" ? PRIMITIVE_TS_TYPE.gtype : renderTsType(context, alias.target);
-    context.module.appendDeclaration(`${renderJsDoc(alias.doc)}export type ${alias.name} = ${targetType};`);
+    const doc = getDoc(alias);
+
+    context.module.appendDeclaration(
+        `${doc}export type ${alias.name} = ${targetType};`,
+        context.declaredType(alias.name),
+    );
 };
 
 const visitClass = (state: TopologicalState, klass: GirClass): void => {

package/src/store/gi/properties.ts

@@ -3,11 +3,12 @@ import type { ModuleContext } from "../../writer/context.js";
 import { collectInterfaceProperties } from "../../analysis/inheritance.js";
 import { renderBracedOrEmpty } from "../../writer/emit.js";
 import { parentCompanionRef } from "./companion.js";
-import { type ResolvedAccessor, resolveOwnerAccessor } from "./property-accessor.js";
+import { propertyDoc, type ResolvedAccessor, resolveOwnerAccessor } from "./property-accessor.js";
 
 const PROPERTIES_SUFFIX = "Properties";
 
-const propertyEntry = (accessor: ResolvedAccessor): string => `${accessor.jsName}: ${accessor.tsType};`;
+const propertyEntry = (accessor: ResolvedAccessor): string =>
+    `${propertyDoc(accessor.property)}${accessor.jsName}: ${accessor.tsType};`;
 
 const interfaceEntries = (context: ModuleContext, klass: GirClass): string[] => {
     const entries: string[] = [];

package/src/store/gi/property-accessor.ts

@@ -6,16 +6,17 @@ import { renderDescriptor } from "../../analysis/descriptor-render.js";
 import { inputParameters } from "../../analysis/param-structure.js";
 import { renderTsType } from "../../analysis/ts-type.js";
 import { type GirProperty, isConstructableProperty } from "../../gir/property.js";
-import { renderJsDoc } from "../../writer/doc.js";
 import { renderBlock } from "../../writer/emit.js";
 import { isEmittableCallable } from "./callables.js";
+import { getDoc } from "./doc-spec.js";
 import { methodExportName, renderMethodReturnType } from "./method.js";
 
 type ResolvedAccessor = {
+    property: GirProperty;
     jsName: string;
     tsType: string;
     hasGetter: boolean;
-    writable: boolean;
+    isWritable: boolean;
     getterMember: string | undefined;
     getterMethod: GirFunction | undefined;
     setterMember: string | undefined;
@@ -136,8 +137,6 @@ const resolveAccessor = (args: PropertyAccessorArgs): ResolvedAccessor | undefin
         return undefined;
     }
 
-    // `g_object_set_property` rejects a construct-only pspec with a critical and drops the write, so
-    // the property is settable at construction time only and must not advertise a setter.
     const isWritable = isConstructableProperty(property) && !property.constructOnly;
     const { member: getterMember, method: getterMethod } = resolveGetterDelegate(args, jsName);
     const { member: setterMember, method: setterMethod } = resolveSetterDelegate(args, jsName, isWritable);
@@ -150,7 +149,7 @@ const resolveAccessor = (args: PropertyAccessorArgs): ResolvedAccessor | undefin
     const ownType = resolveOwnType(context, property, getterMethod, setterMethod);
     const tsType = resolveTsType(args.inheritedType, ownType);
 
-    return { jsName, tsType, hasGetter, writable: isWritable, getterMember, getterMethod, setterMember };
+    return { property, jsName, tsType, hasGetter, isWritable, getterMember, getterMethod, setterMember };
 };
 
 const resolveOwnerAccessor = (
@@ -197,7 +196,7 @@ const renderResolvedPropertyAccessor = (
     property: GirProperty,
     accessor: ResolvedAccessor,
 ): string => {
-    const { jsName, tsType, hasGetter, writable, getterMember, getterMethod, setterMember } = accessor;
+    const { jsName, tsType, hasGetter, isWritable, getterMember, getterMethod, setterMember } = accessor;
     const blocks: string[] = [];
 
     if (hasGetter) {
@@ -205,24 +204,27 @@ const renderResolvedPropertyAccessor = (
         blocks.push(renderBlock(`get ${jsName}(): ${tsType}`, getterBody));
     }
 
-    if (writable) {
+    if (isWritable) {
         const setterBody =
             setterMember === undefined ? renderGenericSetBody(context, property) : `this.${setterMember}(value);`;
 
         blocks.push(renderBlock(`set ${jsName}(value: ${tsType})`, setterBody));
     }
 
-    return `${renderJsDoc(property.doc)}${blocks.join("\n\n")}`;
+    return `${propertyDoc(property)}${blocks.join("\n\n")}`;
 };
 
+const propertyDoc = (property: GirProperty): string =>
+    getDoc(property);
+
 const renderPropertyAccessor = (args: PropertyAccessorArgs): string | undefined =>
     withAccessor(args, (accessor) => renderResolvedPropertyAccessor(args.context, args.property, accessor));
 
 const renderPropertyAccessorSignature = (args: PropertyAccessorArgs): string | undefined =>
-    withAccessor(args, ({ jsName, tsType, hasGetter, writable }) => {
-        const doc = renderJsDoc(args.property.doc);
+    withAccessor(args, ({ jsName, tsType, hasGetter, isWritable }) => {
+        const doc = propertyDoc(args.property);
 
-        if (hasGetter && writable) {
+        if (hasGetter && isWritable) {
             return `${doc}${jsName}: ${tsType};`;
         }
 
@@ -291,6 +293,7 @@ const delegateMember = (
 };
 
 export {
+    propertyDoc,
     resolveAccessor,
     resolveOwnerAccessor,
     resolveAccessorType,

package/src/store/gi/record-constructor.ts

@@ -6,6 +6,7 @@ import type { ModuleContext } from "../../writer/context.js";
 import { renderDescriptor } from "../../analysis/descriptor-render.js";
 import { renderTsType } from "../../analysis/ts-type.js";
 import { renderBlock, renderBracedOrEmpty } from "../../writer/emit.js";
+import { getDoc } from "./doc-spec.js";
 import { renderSourceGtype } from "./gtype-binding.js";
 import { emitFieldWrite, isEmittableField, isInlineField } from "./record-field-accessor.js";
 import { computeRecordFieldSlots, type RecordFieldSlot } from "./record-layout.js";
@@ -33,7 +34,11 @@ const renderRecordConstructorPropsInterface = (
 
     const lines = slots
         .filter((entry): entry is WritableFieldSlot => isWritableFieldSlot(context, entry))
-        .map((entry) => `${toCamelIdentifier(entry.field.name)}?: ${renderTsType(context, entry.field.type, true)};`);
+        .map(
+            (entry) =>
+                `${getDoc(entry.field)}${toCamelIdentifier(entry.field.name)}?: ` +
+                `${renderTsType(context, entry.field.type, true)};`,
+        );
 
     return renderBracedOrEmpty(head, lines.join("\n"));
 };

package/src/store/gi/record-field-accessor.ts

@@ -1,4 +1,5 @@
 import { toCamelIdentifier } from "@gtkx/utils";
+import type { GirAnnotations } from "../../gir/annotations.js";
 import type { GirField } from "../../gir/field.js";
 import type { FieldSlot } from "../../gir/size.js";
 import type { TypeId } from "../../gir/type-id.js";
@@ -7,8 +8,8 @@ import type { ModuleContext } from "../../writer/context.js";
 import { isInlineCallbackRef, renderDescriptor } from "../../analysis/descriptor-render.js";
 import { tStruct } from "../../analysis/descriptor.js";
 import { renderTsType } from "../../analysis/ts-type.js";
-import { renderJsDoc } from "../../writer/doc.js";
 import { indent, renderBlock } from "../../writer/emit.js";
+import { getDoc } from "./doc-spec.js";
 import { bitMask, computeRecordFieldSlots, mergeBitfield, type RecordFieldSlot } from "./record-layout.js";
 import { wrapReturnValue } from "./return-wrap.js";
 import { isValueMarshalable } from "./value-marshalable.js";
@@ -28,8 +29,9 @@ type AdmittedField = {
 type RecordFieldEntry = {
     jsName: string;
     tsType: string;
-    writable: boolean;
+    isWritable: boolean;
     doc: string | undefined;
+    annotations: GirAnnotations;
 };
 
 type InlineFieldVisit = {
@@ -91,8 +93,6 @@ type AccessorOptions = {
     fieldType: TypeId;
 };
 
-// An inline record field is read and written through its own bytes, so it can only be exposed when
-// those bytes are copyable; a pointer field is marshalled as a handle and is always fine.
 const isMarshalableField = (context: ModuleContext, field: GirField): boolean => {
     if (field.cType?.endsWith("*") === true) {
         return true;
@@ -180,8 +180,9 @@ const resolveRecordFieldEntry = (
     return {
         jsName: admitted.jsName,
         tsType: renderTsType(context, admitted.field.type, false),
-        writable: admitted.field.writable,
+        isWritable: admitted.field.writable,
         doc: admitted.field.doc,
+        annotations: admitted.field.annotations,
     };
 };
 
@@ -198,7 +199,7 @@ const renderRecordFieldAccessor = (
     }
 
     const { field, jsName } = admitted;
-    const doc = renderJsDoc(field.doc);
+    const doc = getDoc(field);
     const structArray = renderStructArrayAccessor(context, { field, jsName, slot: slot.slot, siblingFields });
 
     if (structArray !== undefined) {
@@ -211,8 +212,6 @@ const renderRecordFieldAccessor = (
         return `${doc}declare ${jsName}: ${tsType};`;
     }
 
-    // A record field whose C type is the record itself rather than a pointer to it holds the value
-    // in place, so its own address is the value and no word may be loaded out of it.
     const descriptor = context.hoistDescriptor(
         renderDescriptor(context, field.type, "none", { isInline: isInlineField(context, field) }),
     );
@@ -269,8 +268,6 @@ const isAccessorEligibleType = (context: ModuleContext, ref: TypeId): boolean =>
     }
 };
 
-// A field whose record is embedded by value is read and written through its own bytes, so the
-// constructor and the setter have to describe it the same way.
 const isInlineField = (context: ModuleContext, field: GirField): boolean =>
     field.type !== undefined && resolveInlineStructFields(context, field.type, field.cType) !== undefined;
 
@@ -571,7 +568,7 @@ const renderStructArrayAccessor = (context: ModuleContext, target: StructArrayTa
         elementDescriptor: tStruct("borrowed", {
             size: `${lengthExpr} * ${String(elementSize)}`,
             wrapperClass: undefined,
-            callerAllocated: false,
+            isCallerAllocated: false,
         }),
         offset: slot.byteOffset,
         lengthExpr,
@@ -603,7 +600,7 @@ const getterBlock = (options: AccessorOptions): string => {
 
         const wrapped = wrapReturnValue(context, {
             ref: fieldType,
-            nullable: false,
+            isNullable: false,
             valueExpression,
         });
 
@@ -638,5 +635,4 @@ export {
     emitFieldWrite,
     resolveRecordFieldEntry,
     renderRecordFieldAccessor,
-    type RecordFieldEntry,
 };