@gtkx/codegen 1.0.0-rc.4 → 1.1.0

package/src/store/gi/method.ts

@@ -3,6 +3,7 @@ import type { GirFunction } from "../../gir/function.js";
 import type { GirType } from "../../gir/type.js";
 import type { ModuleContext } from "../../writer/context.js";
 import {
+    isSkippedPrimaryReturn,
     renderCallbackType,
     renderDescriptor,
     renderSelfDescriptor,
@@ -14,17 +15,35 @@ 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,
+    renderCallerOutInstance,
+} from "./param-marshal.js";
 
 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;
     asyncFn: GirFunction;
@@ -42,6 +61,11 @@ type CallArgPlan = {
     inputExpr: string | undefined;
 };
 
+type ReturnDescriptorPlan = {
+    descriptor: string;
+    isSkipped: boolean;
+};
+
 type ParamDescriptorOptions = {
     direction?: "out" | "inout";
     isCallerAllocated?: boolean;
@@ -62,7 +86,13 @@ type PlanArgsContext = {
     folded: Set<number>;
 };
 
-const methodExportName = (fn: GirFunction): string => camelCase(fn.name);
+const memberName = (girName: string): string => {
+    const camel = camelCase(girName);
+
+    return /^\d/.test(camel) ? `_${camel}` : camel;
+};
+
+const methodExportName = (fn: GirFunction): string => memberName(fn.name);
 
 const arrayLengthArgument = (source: GirParameter, sourceIndex: number): string => {
     const identifier = parameterIdentifier(source, sourceIndex);
@@ -71,15 +101,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 parameterAnnotation = (context: ModuleContext, fn: GirFunction, parameter: GirParameter): string =>
-    itemComparatorTsType(context, fn, parameter) ?? renderTsType(context, parameter.type, parameter.nullable);
+const closureAnnotation = (context: ModuleContext, base: string): string => {
+    context.addRuntimeTypeImport("ClosureCallback");
+
+    return `${base} | ClosureCallback`;
+};
+
+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 +136,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 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)) {
+        if (isParameterOptional(parameter, options.isOptionalExtra)) {
             hasSeenOptional = true;
         }
 
-        parts.push(formatParameterPart(name, parameterAnnotation(context, fn, parameter), hasSeenOptional));
+        const annotation = parameterAnnotation(context, fn, parameter);
+        parts.push(formatParameterPart(name, annotation, hasSeenOptional));
     }
 
     return parts.join(", ");
@@ -118,9 +163,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 +187,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);
 };
@@ -242,7 +299,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 +310,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);
 
@@ -309,14 +364,16 @@ const paramDescriptorLiteral = (descriptor: string, options: ParamDescriptorOpti
     return `{ ${parts.join(", ")} }`;
 };
 
-const renderReturnDescriptor = (context: ModuleContext, fn: GirFunction): string => {
+const renderReturnDescriptor = (context: ModuleContext, fn: GirFunction): ReturnDescriptorPlan => {
     const instanceOffset = fn.instance === undefined ? 0 : 1;
 
-    return renderDescriptor(context, fn.returnValue.type, fn.returnValue.transferOwnership, {
+    const descriptor = renderDescriptor(context, fn.returnValue.type, fn.returnValue.transferOwnership, {
         argIndexOffset: instanceOffset,
         argIndexMap: emittedArgIndices(fn, instanceOffset),
         isNewlyCreated: fn.instance === undefined,
     });
+
+    return { descriptor, isSkipped: isSkippedPrimaryReturn(context.library, fn.returnValue) };
 };
 
 const planCallArgs = (context: ModuleContext, fn: GirFunction): CallArgPlan[] => {
@@ -405,6 +462,7 @@ const planInoutArgument = (
             : undefined;
 
     return planInoutParam(context, parameter, {
+        fn,
         index,
         argIndex: planContext.argIndex,
         isConsumed: folded.has(index),
@@ -433,7 +491,11 @@ 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,
+        cursor: parameter.cursor,
+        hasOutIndirection: true,
+    });
 
     return {
         paramLiteral: paramDescriptorLiteral(descriptor, { direction: "out", isConsumed }),
@@ -441,41 +503,19 @@ const planOutParam = (
     };
 };
 
-const constructibleName = (
-    context: ModuleContext,
-    ref: GirParameter["type"],
-): { namespaceName: string; typeName: string } | undefined => {
-    let current = ref;
-
-    while (current !== undefined) {
-        const resolved = context.library.typeFor(current);
-
-        if (resolved?.kind === "alias" && resolved.value.target !== undefined) {
-            current = resolved.value.target;
-            continue;
-        }
-
-        return context.library.nameFor(current);
-    }
-
-    return undefined;
-};
-
 const planCallerOut = (
     context: ModuleContext,
     parameter: GirParameter,
     argIndex: ArgIndexOptions,
 ): CallArgPlan => {
     const descriptor = renderDescriptor(context, parameter.type, "none", argIndex);
-    const name = constructibleName(context, parameter.type);
 
-    if (name !== undefined && isCollectibleCallerOut(context, parameter)) {
+    if (isCollectibleCallerOut(context, parameter)) {
         context.addRuntimeImport("getHandle");
-        const classExpression = context.qualify(name.namespaceName, name.typeName);
 
         return {
             paramLiteral: paramDescriptorLiteral(descriptor, { direction: "out", isCallerAllocated: true }),
-            inputExpr: `new ${classExpression}()`,
+            inputExpr: renderCallerOutInstance(context, parameter),
         };
     }
 
@@ -486,13 +526,14 @@ const planInoutParam = (
     context: ModuleContext,
     parameter: GirParameter,
     options: {
+        fn: GirFunction;
         index: number;
         argIndex: ArgIndexOptions;
         isConsumed: boolean;
         lengthSource?: { source: GirParameter; index: number } | undefined;
     },
 ): CallArgPlan => {
-    const { index, argIndex, isConsumed, lengthSource } = options;
+    const { fn, index, argIndex, isConsumed, lengthSource } = options;
 
     if (isHandlePassedInPlace(context, parameter)) {
         const descriptor = renderDescriptor(context, parameter.type, "none", argIndex);
@@ -507,13 +548,16 @@ const planInoutParam = (
         };
     }
 
-    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", isConsumed }),
         inputExpr:
             lengthSource === undefined
-                ? parameterCallExpression(context, parameter, index)
+                ? parameterCallExpression(context, parameter, index, { fn })
                 : arrayLengthArgument(lengthSource.source, lengthSource.index),
     };
 };
@@ -544,27 +588,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`;
@@ -604,8 +651,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;
 
@@ -615,6 +663,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);
     }
@@ -625,9 +677,12 @@ const parameterCallExpression = (
 };
 
 export {
+    isCallbackParameter,
+    memberName,
     methodExportName,
     renderMethodSignature,
     renderMethodReturnType,
+    returnedOutParameters,
     renderPromisifiedBody,
     finishCallExpression,
     renderPromisifiedSignature,

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

@@ -1,7 +1,13 @@
+import { sanitizeTypeIdentifier } from "@gtkx/utils";
 import type { TypeId } from "../../gir/type-id.js";
 import type { GirType } from "../../gir/type.js";
 import type { ModuleContext } from "../../writer/context.js";
 import { type GirParameter, isInoutParameter } from "../../gir/parameter.js";
+import { recordInlineSize } from "./record-layout.js";
+import { isConstructibleRecord } from "./value-marshalable.js";
+
+type TypeName = { namespaceName: string; typeName: string };
+type CallerOutAllocation = TypeName & ({ strategy: "construct" } | { strategy: "allocate"; size: number });
 
 const isHandlePassedInPlace = (context: ModuleContext, parameter: GirParameter): boolean => {
     if (parameter.direction !== "out" && parameter.direction !== "inout") {
@@ -28,14 +34,78 @@ const underlyingType = (context: ModuleContext, ref: TypeId): GirType | undefine
 const underlyingParamKind = (context: ModuleContext, parameter: GirParameter): GirType["kind"] | undefined =>
     parameter.type === undefined ? undefined : underlyingType(context, parameter.type)?.kind;
 
-const isCollectibleCallerOut = (context: ModuleContext, parameter: GirParameter): boolean => {
-    const kind = underlyingParamKind(context, parameter);
+const resolvedTypeName = (context: ModuleContext, ref: TypeId | undefined): TypeName | undefined => {
+    let current = ref;
+
+    while (current !== undefined) {
+        const resolved = context.library.typeFor(current);
+
+        if (resolved?.kind === "alias" && resolved.value.target !== undefined) {
+            current = resolved.value.target;
+            continue;
+        }
+
+        return context.library.nameFor(current);
+    }
+
+    return undefined;
+};
+
+const recordCallerOutAllocation = (
+    context: ModuleContext,
+    name: TypeName,
+    type: Extract<GirType, { kind: "record" }>,
+): CallerOutAllocation | undefined => {
+    const size = recordInlineSize(context, type.value);
+
+    if (size === undefined) {
+        return undefined;
+    }
+
+    return isConstructibleRecord(context, type.namespace.name, type.value)
+        ? { ...name, strategy: "construct" }
+        : { ...name, strategy: "allocate", size };
+};
+
+const callerOutAllocation = (context: ModuleContext, parameter: GirParameter): CallerOutAllocation | undefined => {
+    const name = resolvedTypeName(context, parameter.type);
+    const type = parameter.type === undefined ? undefined : underlyingType(context, parameter.type);
+
+    if (name === undefined || type === undefined) {
+        return undefined;
+    }
+
+    if (type.kind === "class") {
+        return { ...name, strategy: "construct" };
+    }
+
+    return type.kind === "record" ? recordCallerOutAllocation(context, name, type) : undefined;
+};
+
+const renderCallerOutInstance = (context: ModuleContext, parameter: GirParameter): string => {
+    const allocation = callerOutAllocation(context, parameter);
+
+    if (allocation === undefined) {
+        throw new Error("renderCallerOutInstance: expected a caller-allocated out-parameter with a known layout");
+    }
+
+    const classExpression = context.qualify(allocation.namespaceName, sanitizeTypeIdentifier(allocation.typeName));
 
-    return kind === "record" || kind === "class";
+    if (allocation.strategy === "construct") {
+        return `new ${classExpression}()`;
+    }
+
+    context.addRuntimeImport("alloc");
+    context.addRuntimeImport("wrapHandle");
+
+    return `wrapHandle(alloc(${String(allocation.size)}), ${classExpression})`;
 };
 
-const isRecordCallerOut = (context: ModuleContext, parameter: GirParameter): boolean =>
-    underlyingParamKind(context, parameter) === "record";
+const isCollectibleCallerOut = (context: ModuleContext, parameter: GirParameter): boolean =>
+    callerOutAllocation(context, parameter) !== undefined;
+
+const isAllocatableCallerOut = (context: ModuleContext, parameter: GirParameter): boolean =>
+    underlyingParamKind(context, parameter) === "record" && isCollectibleCallerOut(context, parameter);
 
 const isRecordInout = (context: ModuleContext, parameter: GirParameter): boolean =>
     isInoutParameter(parameter) && underlyingParamKind(context, parameter) === "record";
@@ -68,4 +138,19 @@ 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 {
+    isAllocatableCallerOut,
+    isClosureType,
+    isHandlePassedInPlace,
+    isCollectibleCallerOut,
+    isRecordInout,
+    isHandlePassing,
+    renderCallerOutInstance,
+    underlyingType,
+};

package/src/store/gi/pipeline.ts

@@ -1,16 +1,18 @@
+import { sanitizeTypeIdentifier } from "@gtkx/utils";
 import type { GirClass } from "../../gir/class.js";
 import type { Library } from "../../gir/library.js";
 import type { GirAlias, GirNamespace } from "../../gir/namespace.js";
 import { renderTsType } from "../../analysis/ts-type.js";
+import { getParentRef } from "../../gir/ancestry.js";
+import { isEmittableEntity } from "../../gir/emittable.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 { generateNamespaceFunction } from "./function.js";
 import { generateInterface } from "./interface.js";
 import { generateRecord } from "./record.js";
 
@@ -28,6 +30,14 @@ const generateNamespaceModule = (namespace: GirNamespace, library: Library): str
     generateNamespaceTypes(context, namespace);
     generateNamespaceMembers(context, namespace);
 
+    if (!context.module.hasExports()) {
+        throw new Error(
+            `GIR file at ${namespace.girFile} has nothing to generate: its ${namespace.name} namespace produces a ` +
+            "module with no exports, so the file is empty, truncated, or declares only entries GIR marks as not " +
+            "introspectable",
+        );
+    }
+
     return context.module.toSource();
 };
 
@@ -58,8 +68,6 @@ const generateNamespaceMembers = (context: ModuleContext, namespace: GirNamespac
         generateNamespaceFunction(context, fn);
     }
 
-    generateNamespaceBootstrap(context, namespace);
-
     for (const constant of namespace.constants) {
         generateConstant(context, constant);
     }
@@ -70,9 +78,20 @@ const generateNamespaceMembers = (context: ModuleContext, namespace: GirNamespac
 };
 
 const generateAlias = (context: ModuleContext, alias: GirAlias): void => {
+    if (!isEmittableEntity(alias)) {
+        return;
+    }
+
     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);
+    const name = sanitizeTypeIdentifier(alias.name);
+
+    context.declare({
+        name,
+        code: `${doc}export type ${name} = ${targetType};`,
+        owner: alias.name,
+    });
 };
 
 const visitClass = (state: TopologicalState, klass: GirClass): void => {
@@ -119,17 +138,13 @@ const sameNamespaceParent = (
     namespaceName: string,
     byLocalName: Map<string, GirClass>,
 ): GirClass | undefined => {
-    if (klass.parent === undefined) {
-        return undefined;
-    }
-
-    const [parentNamespace, typeName] = splitOptionalNamespace(klass.parent);
+    const parent = getParentRef(klass);
 
-    if (parentNamespace !== undefined && parentNamespace !== namespaceName) {
+    if (parent === undefined || (parent.namespaceName !== undefined && parent.namespaceName !== namespaceName)) {
         return undefined;
     }
 
-    return byLocalName.get(typeName);
+    return byLocalName.get(parent.typeName);
 };
 
 export { generateNamespaceModule };

package/src/store/gi/properties.ts

@@ -1,13 +1,15 @@
 import type { GirClass } from "../../gir/class.js";
 import type { ModuleContext } from "../../writer/context.js";
+import type { Declaration } from "../../writer/module.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.readType};`;
 
 const interfaceEntries = (context: ModuleContext, klass: GirClass): string[] => {
     const entries: string[] = [];
@@ -30,7 +32,7 @@ const renderPropertyDeclarations = (
     klass: GirClass,
     className: string,
     accessors: ResolvedAccessor[],
-): string[] => {
+): Declaration[] => {
     const parentRef = parentCompanionRef(context, klass, PROPERTIES_SUFFIX);
     const extendsClause = parentRef === undefined ? "" : ` extends ${parentRef}`;
 
@@ -42,8 +44,11 @@ const renderPropertyDeclarations = (
     const map = `${className}${PROPERTIES_SUFFIX}`;
 
     return [
-        renderBracedOrEmpty(`export interface ${map}${extendsClause}`, entries.join("\n")),
-        renderBracedOrEmpty(`export interface ${className}`, `__properties__: ${map};`),
+        { name: map, code: renderBracedOrEmpty(`export interface ${map}${extendsClause}`, entries.join("\n")) },
+        {
+            name: className,
+            code: renderBracedOrEmpty(`export interface ${className}`, `__properties__: ${map};`),
+        },
     ];
 };