@gtkx/codegen 1.0.0-rc.4 → 1.0.0

package/src/khronos/render.ts

@@ -1,8 +1,11 @@
-import { lowerFirst, sourceStringLiteral, toCamelIdentifier } from "@gtkx/utils";
+import { sourceStringLiteral, toCamelIdentifier } from "@gtkx/utils";
+import type { GlDocContext } from "./doc-context.js";
 import type { CommandPlan, GlScalar, ReturnPlan } from "./plan.js";
+import type { GlSymbolProvenance } from "./select.js";
 import { tBind, tInlineStruct, tRef, tString, tUint8, tVoid } from "../analysis/descriptor.js";
-import { type OutArg, planArgs, scalarAliasOrGroup, scalarPrefixArgs, trackInto } from "./args.js";
-import { commandJsDoc, inParamDocLine, singularJsDoc } from "./jsdoc.js";
+import { type InArg, type OutArg, planArgs, returnPlanTsType, scalarPrefixArgs, trackInto } from "./args.js";
+import { commandJsDoc, derivedJsDoc, inParamDocLine } from "./jsdoc.js";
+import { commandExportName } from "./notes.js";
 
 type RenderedCommand = {
     exportName: string;
@@ -10,6 +13,12 @@ type RenderedCommand = {
     declaration: string;
 };
 
+type SingularContext = {
+    plan: CommandPlan & { isOk: true };
+    provenance: GlSymbolProvenance;
+    docs: GlDocContext;
+};
+
 type EmittedReturn = {
     tsType: string;
     descriptor: string;
@@ -34,9 +43,6 @@ const glBind = (name: string, argList: string, returnType: string): string =>
         returnType,
     });
 
-const commandExportName = (name: string): string =>
-    toCamelIdentifier(name.startsWith("gl") ? lowerFirst(name.slice(2)) : name);
-
 const singularize = (plural: string): string =>
     plural.endsWith("ies") ? `${plural.slice(0, -3)}y` : plural.replace(/s$/, "");
 
@@ -48,32 +54,27 @@ const buildEmittedReturn = (
     returnGroup: string | undefined,
     usedTypes: Set<string>,
 ): EmittedReturn => {
-    const track = trackInto(usedTypes);
+    const tsType = trackInto(usedTypes)(returnPlanTsType(plan, returnGroup));
+    const cast = (call: string): string => `${call} as ${tsType}`;
 
     switch (plan.kind) {
         case "void": {
-            return { tsType: "void", descriptor: tVoid };
+            return { tsType, descriptor: tVoid };
         }
         case "scalar": {
-            const alias = track(scalarAliasOrGroup(plan.scalar, returnGroup));
-
-            return { tsType: alias, descriptor: plan.scalar.descriptor, expr: (call) => `${call} as ${alias}` };
+            return { tsType, descriptor: plan.scalar.descriptor, expr: cast };
         }
         case "boolean": {
-            return { tsType: "boolean", descriptor: tUint8, expr: (call) => `(${call} as number) !== 0` };
+            return { tsType, descriptor: tUint8, expr: (call) => `(${call} as number) !== 0` };
         }
         case "string": {
-            return { tsType: "string", descriptor: tString("borrowed"), expr: (call) => `${call} as string` };
+            return { tsType, descriptor: tString("borrowed"), expr: cast };
         }
         case "sync": {
-            return { tsType: track("GLsync"), descriptor: tInlineStruct(), expr: (call) => `${call} as GLsync` };
+            return { tsType, descriptor: tInlineStruct(), expr: cast };
         }
         case "opaque-pointer": {
-            return {
-                tsType: track("GLpointer"),
-                descriptor: tInlineStruct(),
-                expr: (call) => `${call} as GLpointer`,
-            };
+            return { tsType, descriptor: tInlineStruct(), expr: cast };
         }
     }
 };
@@ -117,19 +118,20 @@ const returnStatements = (call: string, returned: EmittedReturn, outs: OutArg[])
 };
 
 const renderCommand = (
-    plan: CommandPlan & { ok: true },
-    feature: string,
+    plan: CommandPlan & { isOk: true },
+    provenance: GlSymbolProvenance,
     usedTypes: Set<string>,
+    docs: GlDocContext,
 ): RenderedCommand => {
     const { command } = plan;
     const exportName = commandExportName(command.name);
     const { args, ins, outs } = planArgs(plan, usedTypes);
     const returned = buildEmittedReturn(plan.returnPlan, command.returnGroup, usedTypes);
     const signature = ins.map((arg) => `${arg.name}: ${arg.tsType}`).join(", ");
-    const argNames = args.map((arg) => (arg.out ? arg.cellName : arg.name)).join(", ");
+    const argNames = args.map((arg) => (arg.isOut ? arg.cellName : arg.name)).join(", ");
     const descriptors = renderDescriptorList(args.map((arg) => arg.descriptor));
     const tsReturn = returnTsType(returned, outs);
-    const jsDoc = commandJsDoc({ command, feature, ins, outs, returnPlan: plan.returnPlan });
+    const jsDoc = commandJsDoc({ plan, provenance, ins, outs, docs });
     const seeds = outs.map((out) => out.seed);
     const bindExpression = glBind(command.name, descriptors, returned.descriptor);
     const isInline = plan.params.some((paramPlan) => paramPlan.kind === "string-out");
@@ -150,15 +152,17 @@ const renderCommand = (
     };
 };
 
-const singularCommandJsDoc = (
-    plan: CommandPlan & { ok: true },
-    feature: string,
-    summary: string,
-    body: string[],
-): string => singularJsDoc({ commandName: plan.command.name, feature, summary, body });
+const singularCommandJsDoc = (context: SingularContext, summary: string, body: string[]): string =>
+    derivedJsDoc({
+        command: context.plan.command,
+        provenance: context.provenance,
+        docs: context.docs,
+        summary,
+        body,
+    });
 
 const genSingularScalars = (
-    plan: CommandPlan & { ok: true },
+    plan: CommandPlan & { isOk: true },
 ): { countScalar: GlScalar; outScalar: GlScalar; lenParamName: string } | undefined => {
     const countPlan = plan.params.at(-2);
 
@@ -175,7 +179,7 @@ const genSingularScalars = (
     return { countScalar: countPlan.scalar, outScalar: outPlan.scalar, lenParamName: outPlan.lenParamName };
 };
 
-const genSingularObjectClass = (plan: CommandPlan & { ok: true }, lenParamName: string): string | undefined => {
+const genSingularObjectClass = (plan: CommandPlan & { isOk: true }, lenParamName: string): string | undefined => {
     const countParam = plan.command.params[plan.params.length - 2];
     const outParam = plan.command.params[plan.params.length - 1];
 
@@ -190,7 +194,7 @@ const genSingularObjectClass = (plan: CommandPlan & { ok: true }, lenParamName:
     return outParam.objectClass;
 };
 
-const genSingularShape = (plan: CommandPlan & { ok: true }): GenSingularShape | undefined => {
+const genSingularShape = (plan: CommandPlan & { isOk: true }): GenSingularShape | undefined => {
     const scalars = genSingularScalars(plan);
 
     if (scalars === undefined) {
@@ -206,10 +210,25 @@ const genSingularShape = (plan: CommandPlan & { ok: true }): GenSingularShape |
     return { countScalar: scalars.countScalar, outScalar: scalars.outScalar, objectClass };
 };
 
+const genSingularJsDoc = (context: SingularContext, prefix: InArg[], shape: GenSingularShape): string => {
+    const { command } = context.plan;
+
+    return singularCommandJsDoc(
+        context,
+        `Returns one ${shape.objectClass} object name via ` +
+        `\`${command.name}(${prefix.length > 0 ? "..., " : ""}1, ...)\`.`,
+        [
+            ...prefix.map((arg) => inParamDocLine(context.plan, arg, context.docs)),
+            ` * @returns \`${shape.outScalar.tsAlias}\`, object class \`${shape.objectClass}\``,
+        ],
+    );
+};
+
 const deriveGenSingular = (
-    plan: CommandPlan & { ok: true },
-    feature: string,
+    plan: CommandPlan & { isOk: true },
+    provenance: GlSymbolProvenance,
     usedTypes: Set<string>,
+    docs: GlDocContext,
 ): RenderedCommand | undefined => {
     if (!GEN_FAMILY.test(plan.command.name)) {
         return undefined;
@@ -227,21 +246,14 @@ const deriveGenSingular = (
         return undefined;
     }
 
-    const { countScalar, outScalar, objectClass } = shape;
+    const { countScalar, outScalar } = shape;
     const exportName = singularize(commandExportName(plan.command.name));
     const bindingName = `${plan.command.name}Single`;
     const descriptors = [...prefix.map((arg) => arg.descriptor), countScalar.descriptor, tRef(outScalar.descriptor)];
     usedTypes.add(outScalar.tsAlias);
     const signature = prefix.map((arg) => `${arg.name}: ${arg.tsType}`).join(", ");
     const callArgs = [...prefix.map((arg) => arg.name), "1", "out"].join(", ");
-
-    const jsDoc = singularCommandJsDoc(
-        plan,
-        feature,
-        `Returns one ${objectClass} object name via ` +
-        `\`${plan.command.name}(${prefix.length > 0 ? "..., " : ""}1, ...)\`.`,
-        [...prefix.map((arg) => inParamDocLine(plan.command, arg)), ` * @returns The new ${objectClass} object name`],
-    );
+    const jsDoc = genSingularJsDoc({ plan, provenance, docs }, prefix, shape);
 
     const body = ["    const out = { value: 0 };", `    ${bindingName}(${callArgs});`, "    return out.value;"].join(
         "\n",
@@ -256,7 +268,7 @@ const deriveGenSingular = (
     };
 };
 
-const deleteSingularAlias = (plan: CommandPlan & { ok: true }): string | undefined => {
+const deleteSingularAlias = (plan: CommandPlan & { isOk: true }): string | undefined => {
     if (plan.params.length !== 2) {
         return undefined;
     }
@@ -274,7 +286,7 @@ const deleteSingularAlias = (plan: CommandPlan & { ok: true }): string | undefin
     return arrayPlan.scalar.tsAlias;
 };
 
-const deleteSingularObjectClass = (plan: CommandPlan & { ok: true }): string | undefined => {
+const deleteSingularObjectClass = (plan: CommandPlan & { isOk: true }): string | undefined => {
     const [countParam, arrayParam] = plan.command.params;
 
     if (countParam === undefined || arrayParam === undefined) {
@@ -289,9 +301,10 @@ const deleteSingularObjectClass = (plan: CommandPlan & { ok: true }): string | u
 };
 
 const deriveDeleteSingular = (
-    plan: CommandPlan & { ok: true },
-    feature: string,
+    plan: CommandPlan & { isOk: true },
+    provenance: GlSymbolProvenance,
     usedTypes: Set<string>,
+    docs: GlDocContext,
 ): RenderedCommand | undefined => {
     if (!DELETE_FAMILY.test(plan.command.name)) {
         return undefined;
@@ -313,10 +326,9 @@ const deriveDeleteSingular = (
     const exportName = singularize(commandExportName(plan.command.name));
 
     const jsDoc = singularCommandJsDoc(
-        plan,
-        feature,
+        { plan, provenance, docs },
         `Deletes one ${objectClass} object name via \`${plan.command.name}(1, ...)\`.`,
-        [` * @param name - The ${objectClass} object name to delete`],
+        [` * @param name - \`${scalarAlias}\`, object class \`${objectClass}\``],
     );
 
     return {

package/src/khronos/select.ts

@@ -1,3 +1,4 @@
+import { sortStringsBy } from "@gtkx/utils";
 import type { GlEnum, GlFeature, GlInterfaceBlock, GlRegistry } from "./model.js";
 
 type GlProfile = "core";
@@ -8,60 +9,94 @@ type GlSelection = {
     profile: GlProfile;
 };
 
+type GlSymbolKind = "command" | "enum";
+
+type GlRemoval = {
+    feature: string;
+    comment?: string;
+};
+
+type GlSymbolProvenance = {
+    feature: string;
+    requireComment?: string;
+    removals: GlRemoval[];
+};
+
+type GlRemovedSymbol = {
+    name: string;
+    kind: GlSymbolKind;
+    feature: string;
+    comment?: string;
+};
+
 type GlSubset = {
-    commands: Map<string, string>;
-    enums: Map<string, string>;
+    commands: Map<string, GlSymbolProvenance>;
+    enums: Map<string, GlSymbolProvenance>;
+    removed: GlRemovedSymbol[];
 };
 
-const isBlockApplicable = (block: GlInterfaceBlock, selection: GlSelection): boolean =>
-    block.profile === undefined || block.profile === selection.profile;
+type SelectionState = GlSubset & {
+    history: Map<string, GlRemoval[]>;
+};
 
-const addMissing = (target: Map<string, string>, names: string[], value: string): void => {
-    for (const name of names) {
-        if (!target.has(name)) {
-            target.set(name, value);
-        }
-    }
+type MemberContext = {
+    feature: GlFeature;
+    block: GlInterfaceBlock;
+    kind: GlSymbolKind;
 };
 
-const applyRequires = (
-    feature: GlFeature,
-    selection: GlSelection,
-    commands: Map<string, string>,
-    enums: Map<string, string>,
-): void => {
-    for (const block of feature.requires) {
-        if (!isBlockApplicable(block, selection)) {
-            continue;
-        }
+const isBlockApplicable = (block: GlInterfaceBlock, selection: GlSelection): boolean =>
+    (block.profile === undefined || block.profile === selection.profile) &&
+    (block.api === undefined || block.api === selection.api);
+
+const targetFor = (state: SelectionState, kind: GlSymbolKind): Map<string, GlSymbolProvenance> =>
+    kind === "command" ? state.commands : state.enums;
 
-        addMissing(commands, block.commands, feature.name);
-        addMissing(enums, block.enums, feature.name);
+const commentEntry = (comment: string | undefined): { comment?: string } =>
+    comment === undefined ? {} : { comment };
+
+const requireMember = (state: SelectionState, name: string, context: MemberContext): void => {
+    const target = targetFor(state, context.kind);
+
+    if (target.has(name)) {
+        return;
     }
+
+    const { block, feature } = context;
+
+    target.set(name, {
+        feature: feature.name,
+        ...(block.comment !== undefined && { requireComment: block.comment }),
+        removals: [...(state.history.get(name) ?? [])],
+    });
 };
 
-const removeBlock = (block: GlInterfaceBlock, commands: Map<string, string>, enums: Map<string, string>): void => {
-    for (const name of block.commands) {
-        commands.delete(name);
-    }
+const removeMember = (state: SelectionState, name: string, context: MemberContext): void => {
+    const { block, feature, kind } = context;
+    const removal: GlRemoval = { feature: feature.name, ...commentEntry(block.comment) };
+    targetFor(state, kind).delete(name);
+    state.history.set(name, [...(state.history.get(name) ?? []), removal]);
+    state.removed.push({ name, kind, ...removal });
+};
+
+const applyMembers = (state: SelectionState, names: string[], context: MemberContext): void => {
+    const apply = context.block.kind === "require" ? requireMember : removeMember;
 
-    for (const name of block.enums) {
-        enums.delete(name);
+    for (const name of names) {
+        apply(state, name, context);
     }
 };
 
-const applyRemoves = (
-    feature: GlFeature,
-    selection: GlSelection,
-    commands: Map<string, string>,
-    enums: Map<string, string>,
-): void => {
-    for (const block of feature.removes) {
-        if (!isBlockApplicable(block, selection)) {
-            continue;
-        }
+const applyBlock = (state: SelectionState, feature: GlFeature, block: GlInterfaceBlock): void => {
+    applyMembers(state, block.commands, { feature, block, kind: "command" });
+    applyMembers(state, block.enums, { feature, block, kind: "enum" });
+};
 
-        removeBlock(block, commands, enums);
+const applyFeature = (state: SelectionState, feature: GlFeature, selection: GlSelection): void => {
+    for (const block of feature.blocks) {
+        if (isBlockApplicable(block, selection)) {
+            applyBlock(state, feature, block);
+        }
     }
 };
 
@@ -70,22 +105,28 @@ const selectSubset = (registry: GlRegistry, selection: GlSelection): GlSubset =>
         .filter((feature) => feature.api === selection.api && feature.number <= selection.version)
         .toSorted((a, b) => a.number - b.number);
 
-    const commands: Map<string, string> = new Map();
-    const enums: Map<string, string> = new Map();
-
-    for (const feature of features) {
-        applyRequires(feature, selection, commands, enums);
-    }
+    const state: SelectionState = {
+        commands: new Map(),
+        enums: new Map(),
+        removed: [],
+        history: new Map(),
+    };
 
     for (const feature of features) {
-        applyRemoves(feature, selection, commands, enums);
+        applyFeature(state, feature, selection);
     }
 
-    return { commands, enums };
+    return {
+        commands: state.commands,
+        enums: state.enums,
+        removed: sortStringsBy(state.removed, (entry) => entry.name),
+    };
 };
 
-const resolveEnum = (registry: GlRegistry, name: string): GlEnum => {
-    const found = registry.enums.find((candidate) => candidate.name === name);
+const resolveEnum = (registry: GlRegistry, name: string, api: string): GlEnum => {
+    const found = registry.enums.find(
+        (candidate) => candidate.name === name && (candidate.api === undefined || candidate.api === api),
+    );
 
     if (found === undefined) {
         throw new Error(`Enum token ${name} has no definition in the registry`);
@@ -94,4 +135,4 @@ const resolveEnum = (registry: GlRegistry, name: string): GlEnum => {
     return found;
 };
 
-export { selectSubset, resolveEnum, type GlSelection };
+export { selectSubset, resolveEnum, type GlRemoval, type GlSelection, type GlSubset, type GlSymbolProvenance };

package/src/react/element-config.ts

@@ -1,4 +1,4 @@
-import type { ModuleExport } from "@gtkx/react/internal";
+import type { ModuleExport } from "@gtkx/react/config";
 import { readdirSync } from "node:fs";
 import type { OmittedProps } from "../store/jsx/omitted-props.js";
 
@@ -96,5 +96,5 @@ const readBuiltinElements = async (reactSubexports: string[], giStoreDir: string
     return result;
 };
 
-export type { ModuleExport } from "@gtkx/react/internal";
+export type { ModuleExport } from "@gtkx/react/config";
 export { readBuiltinElements, type BuiltinElements };

package/src/runner.ts

@@ -1,5 +1,6 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import type { ModuleExport } from "./react/element-config.js";
 import type { OmittedProps } from "./store/jsx/omitted-props.js";
 import type { StoreOptions } from "./store/store-fs.js";
 import { checkModules } from "./compile.js";
@@ -8,14 +9,6 @@ import { runGiCodegen } from "./gi.js";
 import { Library } from "./gir/library.js";
 import { generateGlModules, type GlGenerationReport } from "./khronos/pipeline.js";
 
-/** A named export in a module, referenced as plain data (the module is never imported at runtime). */
-type ModuleExport = {
-    /** Specifier the export is imported from. */
-    module: string;
-    /** Identifier the module exports it under. */
-    export: string;
-};
-
 type GlCodegenOptions = {
     registryPath: string;
     overrideExports: Set<string>;

package/src/store/compile-store.ts

@@ -51,4 +51,4 @@ const compileStore = (params: CompileStoreParams): void => {
     }
 };
 
-export { compileStore, type CompileStoreParams };
+export { compileStore };

package/src/store/gi/callable-doc.ts

@@ -0,0 +1,102 @@
+import type { GirFunction } from "../../gir/function.js";
+import type { GirCallable } from "../../gir/parameter.js";
+import type { ModuleContext } from "../../writer/context.js";
+import type { JsDocSpec } from "../../writer/doc.js";
+import { shouldOmitPrimaryReturn } from "../../analysis/descriptor-render.js";
+import { nulTerminatedByteParams } from "../../analysis/nul-terminated-bytes.js";
+import {
+    documentedParameters,
+    type InputParameter,
+    parameterIdentifier,
+    renamesWithInstance,
+} from "../../analysis/param-structure.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import { annotationSpec, THROWS_TEXT } from "./doc-spec.js";
+import { isCallbackParameter, returnedOutParameters } from "./method.js";
+
+type CallableDocOptions = {
+    finishFn?: GirFunction | undefined;
+    renames?: Map<string, string> | undefined;
+};
+
+const WHITESPACE_RUN_PATTERN = /\s+/g;
+
+const nulTerminatedNote = (context: ModuleContext, callable: GirCallable): string | undefined => {
+    const parameters = nulTerminatedByteParams(context.library, callable);
+
+    if (parameters.length === 0) {
+        return undefined;
+    }
+
+    const names = parameters.map((parameter) => `\`${parameter.name}\``).join(", ");
+
+    return [
+        `The C function reads ${names} as a NUL-terminated string, so it stops at the`,
+        "first zero byte and drops every byte after it without reporting an error.",
+        "Pass binary data through a `GLib.Bytes` route such as `GLib.Variant.newFromBytes`",
+        "instead.",
+    ].join("\n");
+};
+
+const tupleBullet = (name: string, doc: string | undefined): string | undefined => {
+    const text = (doc ?? "").replaceAll(WHITESPACE_RUN_PATTERN, " ").trim();
+
+    return text.length === 0 ? undefined : `- \`${name}\`: ${text}`;
+};
+
+const tupleReturnsText = (primary: string | undefined, outs: InputParameter[]): string | undefined => {
+    const bullets = [
+        tupleBullet("result", primary),
+        ...outs.map(({ parameter, index }) => tupleBullet(parameterIdentifier(parameter, index), parameter.doc)),
+    ].filter((bullet) => bullet !== undefined);
+
+    return bullets.length === 0 ? undefined : `Tuple of:\n\n${bullets.join("\n")}`;
+};
+
+const returnsText = (context: ModuleContext, fn: GirFunction): string | undefined => {
+    const outs = returnedOutParameters(context, fn);
+    const isPrimaryOmitted = shouldOmitPrimaryReturn(context.library, fn.returnValue);
+    const primary = isPrimaryOmitted ? undefined : fn.returnValue.doc;
+
+    if (outs.length === 0) {
+        return primary;
+    }
+
+    if (isPrimaryOmitted && outs.length === 1) {
+        return outs[0]?.parameter.doc;
+    }
+
+    return tupleReturnsText(primary, outs);
+};
+
+const docIdentifiers = (callable: GirFunction, renames: Map<string, string> | undefined): Map<string, string> => {
+    const identifiers = renamesWithInstance(callable.parameters, callable.instance);
+    const overrides = renames ?? new Map<string, string>();
+
+    for (const [girName, declaredName] of overrides) {
+        identifiers.set(girName, declaredName);
+    }
+
+    return identifiers;
+};
+
+const canCallableThrow = (callable: GirFunction, finishFn: GirFunction | undefined): boolean =>
+    callable.throws || finishFn?.throws === true;
+
+const callableSpec = (context: ModuleContext, callable: GirFunction, options: CallableDocOptions): JsDocSpec => ({
+    ...annotationSpec(callable.annotations),
+    identifiers: docIdentifiers(callable, options.renames),
+    params: documentedParameters(
+        context.library,
+        callable,
+        (parameter) => options.finishFn !== undefined && isCallbackParameter(context, parameter),
+        options.renames,
+    ),
+    returns: returnsText(context, options.finishFn ?? callable),
+    throws: canCallableThrow(callable, options.finishFn) ? THROWS_TEXT : undefined,
+});
+
+const callableDoc = (context: ModuleContext, callable: GirFunction, options: CallableDocOptions = {}): string =>
+    renderJsDoc(callable.doc, nulTerminatedNote(context, callable), callableSpec(context, callable, options));
+
+export { callableDoc, callableSpec };

package/src/store/gi/callables.ts

@@ -1,10 +1,11 @@
 import { camelCase, toCamelIdentifier, uniqBy } from "@gtkx/utils";
 import type { GirFunction } from "../../gir/function.js";
 import type { ModuleContext } from "../../writer/context.js";
-import { hasCallerAllocatedArrayLength } from "../../analysis/param-structure.js";
-import { renderJsDoc } from "../../writer/doc.js";
+import type { JsDocSpec } from "../../writer/doc.js";
+import { hasUnmarshalableParam } from "../../analysis/param-capability.js";
 import { renderBlock } from "../../writer/emit.js";
 import { matchAsyncFinish } from "./async.js";
+import { callableDoc, callableSpec } from "./callable-doc.js";
 import { renderFnExpression } from "./function.js";
 import { gtypeMemberDeclaration } from "./gtype-binding.js";
 import {
@@ -16,7 +17,7 @@ import {
     renderPromisifiedBody,
     renderPromisifiedSignature,
 } from "./method.js";
-import { renderRuntimeOverride } from "./runtime-override.js";
+import { renderRuntimeOverride, runtimeOverrideRenames } from "./runtime-override.js";
 
 type Callables = {
     constructors: GirFunction[];
@@ -64,7 +65,7 @@ type PlainTypeMembersOptions = {
 
 const renderInstanceMethodSignature: InstanceMemberRenderer = instanceMemberRenderer(
     (context, callable, { name, finishFn }) =>
-        `${renderJsDoc(callable.doc)}${memberSignatureText(context, callable, name, { finishFn })};`,
+        `${memberDoc(context, callable, finishFn)}${memberSignatureText(context, callable, name, { finishFn })};`,
 );
 
 const renderClassInstanceMember: InstanceMemberRenderer = instanceMemberRenderer(
@@ -78,6 +79,12 @@ const renderClassInstanceMember: InstanceMemberRenderer = instanceMemberRenderer
                 }),
 );
 
+const memberDoc = (context: ModuleContext, callable: GirFunction, finishFn: GirFunction | undefined): string =>
+    callableDoc(context, callable, { finishFn });
+
+const instanceMemberSpec = (context: ModuleContext, callable: GirFunction, scope: InstanceScope): JsDocSpec =>
+    callableSpec(context, callable, { finishFn: matchFinishFunction(context, callable, scope) });
+
 const instanceScope = (ownerName: string, callables: Callables): InstanceScope => ({
     ownerName,
     methodByName: indexMethodsByName(callables.methods),
@@ -96,11 +103,7 @@ const renderBinding = (
     context: ModuleContext,
     callable: GirFunction,
 ): { text: string; cIdentifier: string } | undefined => {
-    if (!callable.introspectable) {
-        return undefined;
-    }
-
-    if (callable.shadowedBy !== undefined) {
+    if (!isEmittableCallable(context, callable)) {
         return undefined;
     }
 
@@ -182,7 +185,8 @@ const renderCallableMember = (
     }
 
     const { cIdentifier, name } = resolved;
-    const doc = renderJsDoc(callable.doc);
+    const renames = options.canUseRuntimeOverride === true ? runtimeOverrideRenames(callable) : undefined;
+    const doc = callableDoc(context, callable, { renames });
     const override = runtimeOverrideMember(callable, name, doc, options.canUseRuntimeOverride);
 
     if (override !== undefined) {
@@ -349,7 +353,7 @@ const renderPromisifiedCallable = (
     const prefix = member.isStatic ? "static " : "";
     const header = `${prefix}${member.name}(${signature}): ${returnType}`;
 
-    return `${renderJsDoc(callable.doc)}${renderBlock(header, body)}`;
+    return `${memberDoc(context, callable, finishFn)}${renderBlock(header, body)}`;
 };
 
 const indexMethodsByName = (methods: GirFunction[]): Map<string, GirFunction> => {
@@ -366,7 +370,7 @@ const isEmittableCallable = (context: ModuleContext, callable: GirFunction): boo
     callable.introspectable &&
     callable.shadowedBy === undefined &&
     callable.cIdentifier !== undefined &&
-    !hasCallerAllocatedArrayLength(context.library, callable);
+    !hasUnmarshalableParam(context, callable);
 
 const constructorMemberName = (girName: string): string | undefined => {
     const camel = camelCase(girName);
@@ -497,6 +501,7 @@ const renderPlainTypeMembers = (
 export {
     renderInstanceMethodSignature,
     renderClassInstanceMember,
+    instanceMemberSpec,
     instanceScope,
     dedupeCallables,
     generateBindings,
@@ -508,5 +513,6 @@ export {
     renderStaticHead,
     renderPlainTypeMembers,
     type Callables,
+    type InstanceMemberRenderer,
     type InstanceScope,
 };