@gtkx/codegen 1.0.0-rc.4 → 1.0.0

package/src/store/gi/callback.ts

@@ -1,6 +1,6 @@
 import type { ModuleContext } from "../../writer/context.js";
 import { callbackAsFunction, type GirCallback } from "../../gir/callback.js";
-import { renderJsDoc } from "../../writer/doc.js";
+import { callableDoc } from "./callable-doc.js";
 import { renderMethodReturnType, renderMethodSignature } from "./method.js";
 
 const generateCallback = (context: ModuleContext, callback: GirCallback): void => {
@@ -17,7 +17,8 @@ const generateCallback = (context: ModuleContext, callback: GirCallback): void =
     const returnType = renderMethodReturnType(context, fn);
 
     context.module.appendDeclaration(
-        `${renderJsDoc(callback.doc)}export type ${callback.name} = (${signature}) => ${returnType};`,
+        `${callableDoc(context, fn)}export type ${callback.name} = (${signature}) => ${returnType};`,
+        context.declaredType(callback.name),
     );
 };
 

package/src/store/gi/class.ts

@@ -11,7 +11,6 @@ import {
 } from "../../analysis/inheritance.js";
 import { ancestorChain, type ResolvedAncestor } from "../../gir/ancestry.js";
 import { splitOptionalNamespace } from "../../gir/type-ref.js";
-import { renderJsDoc } from "../../writer/doc.js";
 import { indentMembers } from "../../writer/emit.js";
 import {
     type Callables,
@@ -24,13 +23,14 @@ import {
     renderStaticHead,
 } from "./callables.js";
 import { renderClassConstructor, renderConstructorPropsInterface } from "./constructor-props.js";
+import { getDoc } from "./doc-spec.js";
 import { gtypeMemberDeclaration, renderSourceGtype } from "./gtype-binding.js";
 import { methodExportName } from "./method.js";
 import { renderPropertyDeclarations } from "./properties.js";
 import { renderResolvedPropertyAccessor, resolveAccessor, type ResolvedAccessor } from "./property-accessor.js";
 import { appendWrapperClassRegistration } from "./registration.js";
 import { renderSignalDeclarations, renderSignalMembers } from "./signal.js";
-import { renderVfuncMetadata } from "./vtable.js";
+import { renderVfuncMembers, renderVfuncMetadata } from "./vtable.js";
 
 type ImplementedRef = {
     typeRef: string;
@@ -84,9 +84,11 @@ const generateClass = (context: ModuleContext, klass: GirClass): void => {
     const implementsClause = typeRefs.length === 0 ? "" : ` implements ${typeRefs.join(", ")}`;
     const { members, accessors } = renderClassMembers(context, klass, callables, parentExpression !== undefined);
     const body = indentMembers(members);
+    const doc = getDoc(klass);
 
     context.module.appendDeclaration(
-        `${renderJsDoc(klass.doc)}export class ${className}${extendsClause}${implementsClause} {\n${body}\n}`,
+        `${doc}export class ${className}${extendsClause}${implementsClause} {\n${body}\n}`,
+        context.declaredType(className),
     );
 
     context.module.appendDeclaration(renderConstructorPropsInterface(context, klass, className));
@@ -152,6 +154,7 @@ const renderClassMembers = (
         className,
     });
 
+    members.push(...renderVfuncMembers({ context, klass, mode: "implementation" }));
     const inheritedPropertyTypes = collectInheritedPropertyTypes(context, klass);
     const accessors: ResolvedAccessor[] = [];
 

package/src/store/gi/closure-invocation.ts

@@ -0,0 +1,26 @@
+import type { GirFunction } from "../../gir/function.js";
+
+const FUNCTIONS_INVOKING_CLOSURE_PARAMETERS: Set<string> = new Set([
+    "g_binding_group_bind_with_closures",
+    "g_bus_own_name_on_connection_with_closures",
+    "g_bus_own_name_with_closures",
+    "g_bus_watch_name_on_connection_with_closures",
+    "g_bus_watch_name_with_closures",
+    "g_dbus_connection_register_object_with_closures",
+    "g_dbus_connection_register_object_with_closures2",
+    "g_file_copy_async_with_closures",
+    "g_file_move_async_with_closures",
+    "g_object_bind_property_with_closures",
+    "g_settings_bind_with_mapping_closures",
+    "g_signal_connect_closure",
+    "g_signal_connect_closure_by_id",
+    "g_signal_group_connect_closure",
+    "g_signal_override_class_closure",
+    "g_source_set_closure",
+    "gtk_closure_expression_new",
+]);
+
+const areClosuresInvoked = (fn: GirFunction): boolean =>
+    fn.cIdentifier !== undefined && FUNCTIONS_INVOKING_CLOSURE_PARAMETERS.has(fn.cIdentifier);
+
+export { areClosuresInvoked };

package/src/store/gi/constant.ts

@@ -3,15 +3,14 @@ import type { GirConstant } from "../../gir/namespace.js";
 import type { PrimitiveCategory } from "../../gir/primitives.js";
 import type { TypeId } from "../../gir/type-id.js";
 import type { ModuleContext } from "../../writer/context.js";
-import { renderJsDoc } from "../../writer/doc.js";
+import { getDoc } from "./doc-spec.js";
 
 const TRUE_VALUES: Set<string> = new Set(["true", "1"]);
 const BIGINT_CATEGORIES: Set<PrimitiveCategory> = new Set(["bigint64", "biguint64", "gtype"]);
 
 const generateConstant = (context: ModuleContext, constant: GirConstant): void => {
-    context.module.appendDeclaration(
-        `${renderJsDoc(constant.doc)}export const ${constant.name} = ${constantLiteral(context, constant)};`,
-    );
+    const doc = getDoc(constant);
+    context.module.appendDeclaration(`${doc}export const ${constant.name} = ${constantLiteral(context, constant)};`);
 };
 
 const constantLiteral = (context: ModuleContext, constant: GirConstant): string => {

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

@@ -8,8 +8,7 @@ import { ancestorChain } from "../../gir/ancestry.js";
 import { type GirProperty, isConstructableProperty } from "../../gir/property.js";
 import { renderBlock, renderBraced, renderBracedOrEmpty } from "../../writer/emit.js";
 import { parentCompanionRef } from "./companion.js";
-
-const PROPS_RECORD = "Record<string, unknown>";
+import { propertyDoc } from "./property-accessor.js";
 
 const constructablePropNames = (klass: GirClass): string[] =>
     klass.properties.filter(isConstructableProperty).map((property) => toCamelIdentifier(property.name));
@@ -47,7 +46,8 @@ const renderConstructorPropsInterface = (context: ModuleContext, klass: GirClass
 
     const lines = collectConstructableProps(context, klass).map(
         (property) =>
-            `${toCamelIdentifier(property.name)}?: ${renderTsType(context, property.type, true)} | undefined;`,
+            `${propertyDoc(property)}${toCamelIdentifier(property.name)}?: ` +
+            `${renderTsType(context, property.type, true)} | undefined;`,
     );
 
     return renderBracedOrEmpty(`export interface ${className}ConstructorProps${extendsClause}`, lines.join("\n"));
@@ -73,36 +73,32 @@ const renderClassConstructor = (
 };
 
 const renderRootConstructor = (context: ModuleContext): string => {
-    context.addRuntimeImport("getInstanceType");
+    context.addRuntimeTypeImport("AnyClass");
+    context.addRuntimeImport("getClassType");
     context.addRuntimeImport("newObjectWithProperties");
-    context.addRuntimeImport("setHandle");
-    context.addRuntimeImport("setWrapper");
-
-    const body = [
-        "const handle = newObjectWithProperties(getInstanceType(this), props);",
-        "setHandle(this, handle);",
-        "setWrapper(handle, this);",
-    ].join("\n");
+    const body = "newObjectWithProperties(getClassType(this.constructor as AnyClass), props, this);";
 
-    return renderBlock(`constructor(props: ${PROPS_RECORD} = {})`, body);
+    return renderBlock("constructor(props: object = {})", body);
 };
 
-const renderTranslatingConstructor = (context: ModuleContext, props: GirProperty[], className: string): string => {
-    context.addRuntimeImport("t");
-    const destructured = props.map((property) => toCamelIdentifier(property.name));
-    const pattern = `{ ${[...destructured, "...rest"].join(", ")} }`;
-
+const renderConstructBindings = (context: ModuleContext, props: GirProperty[]): string => {
     const entries = props.map((property) => {
         const descriptor = renderDescriptor(context, property.type, property.transferOwnership);
+        const key = sourceStringLiteral(toCamelIdentifier(property.name));
 
-        return `${sourceStringLiteral(property.name)}: [${descriptor}, ${toCamelIdentifier(property.name)}],`;
+        return `${key}: [${sourceStringLiteral(property.name)}, ${descriptor}],`;
     });
 
-    const recordLiteral = renderBraced(entries.join("\n"));
-    const lines = [`const props: ${PROPS_RECORD} = ${recordLiteral};`, "super({ ...props, ...rest });"];
-    const body = lines.join("\n");
+    return renderBraced(entries.join("\n"));
+};
+
+const renderTranslatingConstructor = (context: ModuleContext, props: GirProperty[], className: string): string => {
+    context.addRuntimeImport("t");
+    context.addRuntimeImport("registerConstructProperties");
+    const bindings = renderConstructBindings(context, props);
+    context.module.appendRegistration(`registerConstructProperties(${className}, ${bindings});`);
 
-    return renderBlock(`constructor(${pattern}: ${className}ConstructorProps = {})`, body);
+    return renderBlock(`constructor(props: ${className}ConstructorProps = {})`, "super(props);");
 };
 
 export { renderConstructorPropsInterface, renderClassConstructor };

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

@@ -0,0 +1,38 @@
+import type { GirAnnotations } from "../../gir/annotations.js";
+import type { GirCallable, GirParameter } from "../../gir/parameter.js";
+import type { JsDocSpec } from "../../writer/doc.js";
+import { documentedHandlerParameters, handlerRenames } from "../../analysis/param-structure.js";
+import { renderJsDoc } from "../../writer/doc.js";
+
+type DocumentedNode = { doc: string | undefined; annotations: GirAnnotations };
+
+const SELF_PARAM_DOC = "The instance the signal was emitted on.";
+const THROWS_TEXT = "A `GLib.Error` carrying the failing operation's domain, code, and message.";
+
+const annotationSpec = (annotations: GirAnnotations): JsDocSpec => ({
+    deprecated: annotations.isDeprecated
+        ? { since: annotations.deprecatedSince, doc: annotations.deprecationDoc }
+        : undefined,
+    since: annotations.since,
+});
+
+const getDoc = (node: DocumentedNode): string => renderJsDoc(node.doc, undefined, annotationSpec(node.annotations));
+
+const handlerSpec = (
+    callable: GirCallable,
+    parameters: GirParameter[],
+    identifiers?: Map<string, string>,
+): JsDocSpec => ({
+    ...annotationSpec(callable.annotations),
+    identifiers: identifiers ?? handlerRenames(parameters),
+    params: documentedHandlerParameters(parameters),
+    returns: callable.returnValue.doc,
+});
+
+const selfHandlerSpec = (signal: GirCallable): JsDocSpec => {
+    const spec = handlerSpec(signal, signal.parameters);
+
+    return { ...spec, params: [...(spec.params ?? []), { name: "self", doc: SELF_PARAM_DOC }] };
+};
+
+export { annotationSpec, getDoc, handlerSpec, selfHandlerSpec, THROWS_TEXT };

package/src/store/gi/enum.ts

@@ -1,47 +1,82 @@
 import { sourceStringLiteral } from "@gtkx/utils";
-import type { GirEnum } from "../../gir/enum.js";
+import type { EnumMember, GirEnum } from "../../gir/enum.js";
 import type { ModuleContext } from "../../writer/context.js";
-import { renderJsDoc } from "../../writer/doc.js";
+import { hasAnnotations } from "../../gir/annotations.js";
 import { indent } from "../../writer/emit.js";
+import { getDoc } from "./doc-spec.js";
+
+type KeyedMember = EnumMember & { key: string };
+
+const memberDoc = (member: KeyedMember): string =>
+    getDoc(member);
+
+const enumDoc = (enumeration: GirEnum): string =>
+    getDoc(enumeration);
 
 const generateEnum = (context: ModuleContext, enumeration: GirEnum): void => {
     if (!enumeration.introspectable) {
         return;
     }
 
-    const name = enumeration.name;
     const members = enumeration.members.map((member) => ({ ...member, key: enumMemberKey(member.name) }));
+    const errorDomain = enumeration.errorDomain;
 
-    if (enumeration.errorDomain !== undefined) {
-        const memberEntries = members.map((member) => `${member.key}: ${member.value}`);
-        const typeFields = members.map((member) => `${member.key}: number`).join("; ");
-        context.addRuntimeImport("createErrorDomain");
-        context.addRuntimeImport("ErrorDomain");
-        const quarkExpression = renderQuarkExpression(context, enumeration.errorDomain);
-        context.module.appendDeclaration(`${renderJsDoc(enumeration.doc)}export type ${name} = number;`);
-
-        context.module.appendDeclaration(
-            `export const ${name}: ErrorDomain<{ ${typeFields} }> = ` +
-            `createErrorDomain(${quarkExpression}, { ${memberEntries.join(", ")} });`,
-        );
+    if (errorDomain !== undefined) {
+        appendErrorDomain(context, enumeration, members, errorDomain);
 
         return;
     }
 
-    if (members.some((member) => member.doc !== undefined)) {
-        const memberBlocks = members.map((member) => `${renderJsDoc(member.doc)}${member.key} = ${member.value},`);
+    appendEnumDeclaration(context, enumeration, members);
+};
+
+const appendErrorDomain = (
+    context: ModuleContext,
+    enumeration: GirEnum,
+    members: KeyedMember[],
+    errorDomain: string,
+): void => {
+    const memberEntries = members.map((member) => `${member.key}: ${member.value}`);
+    const typeFields = members.map((member) => `${memberDoc(member)}${member.key}: number;`);
+    context.addRuntimeImport("createErrorDomain");
+    context.addRuntimeImport("ErrorDomain");
+    const quarkExpression = renderQuarkExpression(context, errorDomain);
+    const doc = enumDoc(enumeration);
+    const shape = typeFields.length === 0 ? "{}" : `{\n${indent(typeFields.join("\n"), 1)}\n}`;
+
+    context.module.appendDeclaration(
+        `${doc}export type ${enumeration.name} = number;`,
+        context.declaredType(enumeration.name),
+    );
+
+    context.module.appendDeclaration(
+        `${doc}export const ${enumeration.name}: ErrorDomain<${shape}> = ` +
+        `createErrorDomain(${quarkExpression}, { ${memberEntries.join(", ")} });`,
+    );
+};
+
+const isMemberDocumented = (member: KeyedMember): boolean =>
+    member.doc !== undefined || hasAnnotations(member.annotations);
+
+const appendEnumDeclaration = (context: ModuleContext, enumeration: GirEnum, members: KeyedMember[]): void => {
+    const doc = enumDoc(enumeration);
+
+    if (members.some((member) => isMemberDocumented(member))) {
+        const blocks = members.map((member) => `${memberDoc(member)}${member.key} = ${member.value},`);
 
         context.module.appendDeclaration(
-            `${renderJsDoc(enumeration.doc)}export enum ${name} {\n${indent(memberBlocks.join("\n"), 1)}\n}`,
+            `${doc}export enum ${enumeration.name} {\n${indent(blocks.join("\n"), 1)}\n}`,
+            context.declaredType(enumeration.name),
         );
 
         return;
     }
 
-    const memberDeclarations = members.map((member) => `${member.key} = ${member.value}`);
+    const declarations = members.map((member) => `${member.key} = ${member.value}`);
 
     context.module.appendDeclaration(
-        `${renderJsDoc(enumeration.doc)}export enum ${name} { ${memberDeclarations.join(", ")} }`,
+        `${doc}export enum ${enumeration.name} { ${declarations.join(", ")} }`,
+        context.declaredType(enumeration.name),
     );
 };
 

package/src/store/gi/function.ts

@@ -3,10 +3,10 @@ import type { GirFunction } from "../../gir/function.js";
 import type { GirNamespace } from "../../gir/namespace.js";
 import type { ModuleContext } from "../../writer/context.js";
 import { tFn } from "../../analysis/descriptor.js";
-import { hasCallerAllocatedArrayLength } from "../../analysis/param-structure.js";
-import { renderJsDoc } from "../../writer/doc.js";
+import { hasUnmarshalableParam } from "../../analysis/param-capability.js";
 import { arrayLiteral, renderBlock } from "../../writer/emit.js";
 import { matchAsyncFinish } from "./async.js";
+import { callableDoc } from "./callable-doc.js";
 import {
     planCallArgs,
     renderMethodBody,
@@ -17,6 +17,19 @@ import {
     renderReturnDescriptor,
 } from "./method.js";
 
+type NamespaceFinish = {
+    fn: GirFunction;
+    exportName: string;
+};
+
+type NamespaceFunctionOptions = {
+    context: ModuleContext;
+    fn: GirFunction;
+    finish: NamespaceFinish | undefined;
+    exportName: string;
+    bindingName: string;
+};
+
 const renderFnExpression = (context: ModuleContext, fn: GirFunction): string | undefined => {
     if (fn.cIdentifier === undefined) {
         return undefined;
@@ -58,7 +71,7 @@ const canEmitNamespaceFunction = (context: ModuleContext, fn: GirFunction): bool
     !isMovedOntoEmittedMember(context, fn) &&
     fn.shadowedBy === undefined &&
     fn.cIdentifier !== undefined &&
-    !hasCallerAllocatedArrayLength(context.library, fn);
+    !hasUnmarshalableParam(context, fn);
 
 const generateNamespaceFunction = (context: ModuleContext, fn: GirFunction): void => {
     if (!canEmitNamespaceFunction(context, fn)) {
@@ -80,30 +93,39 @@ const generateNamespaceFunction = (context: ModuleContext, fn: GirFunction): voi
     const bindingName = toCamelIdentifier(cIdentifier);
     context.module.appendBinding(`const ${bindingName} = ${expression};`, cIdentifier);
     const exportName = namespaceFunctionExportName(cIdentifier, fn.name, context.namespace.cSymbolPrefixes);
-    const declaration = renderNamespaceFunctionDeclaration(context, fn, exportName, bindingName);
-    context.module.appendDeclaration(`${renderJsDoc(fn.doc)}${declaration}`);
+    const finish = matchNamespaceFinish(context, fn);
+    const declaration = renderNamespaceFunctionDeclaration({ context, fn, finish, exportName, bindingName });
+    const doc = callableDoc(context, fn, { finishFn: finish?.fn });
+    context.module.appendDeclaration(`${doc}${declaration}`);
 };
 
-const renderNamespaceFunctionDeclaration = (
-    context: ModuleContext,
-    fn: GirFunction,
-    exportName: string,
-    bindingName: string,
-): string => {
+const matchNamespaceFinish = (context: ModuleContext, fn: GirFunction): NamespaceFinish | undefined => {
     const finishFn = matchAsyncFinish(context.library, fn, context.namespace.functions);
-    const finishCIdentifier = finishFn?.cIdentifier;
+    const cIdentifier = finishFn?.cIdentifier;
+
+    if (finishFn === undefined || cIdentifier === undefined || !canEmitNamespaceFunction(context, finishFn)) {
+        return undefined;
+    }
+
+    return {
+        fn: finishFn,
+        exportName: namespaceFunctionExportName(cIdentifier, finishFn.name, context.namespace.cSymbolPrefixes),
+    };
+};
 
-    if (finishFn !== undefined && finishCIdentifier !== undefined && canEmitNamespaceFunction(context, finishFn)) {
-        const finishExport = namespaceFunctionExportName(
-            finishCIdentifier,
-            finishFn.name,
-            context.namespace.cSymbolPrefixes,
-        );
+const renderPromisifiedNamespaceFunction = (options: NamespaceFunctionOptions, finish: NamespaceFinish): string => {
+    const { context, fn, exportName, bindingName } = options;
+    const { signature, returnType } = renderPromisifiedSignature(context, fn, finish.fn);
+    const body = renderPromisifiedBody(context, fn, finish.exportName, bindingName);
+
+    return renderBlock(`export function ${exportName}(${signature}): ${returnType}`, body);
+};
 
-        const { signature, returnType } = renderPromisifiedSignature(context, fn, finishFn);
-        const body = renderPromisifiedBody(context, fn, finishExport, bindingName);
+const renderNamespaceFunctionDeclaration = (options: NamespaceFunctionOptions): string => {
+    const { context, fn, finish, exportName, bindingName } = options;
 
-        return renderBlock(`export function ${exportName}(${signature}): ${returnType}`, body);
+    if (finish !== undefined) {
+        return renderPromisifiedNamespaceFunction(options, finish);
     }
 
     const signature = renderMethodSignature(context, fn);