@gtkx/codegen 1.0.0-rc.1 → 1.0.0-rc.2

package/src/store/jsx/props.ts

@@ -0,0 +1,274 @@
+import { toCamelIdentifier, upperFirst } from "@gtkx/utils";
+import type { GirClass } from "../../gir/class.js";
+import type { Library } from "../../gir/library.js";
+import type { GirNamespace } from "../../gir/namespace.js";
+import type { GirCallable } from "../../gir/parameter.js";
+import type { TypeId } from "../../gir/type-id.js";
+import { forEachAncestor } from "../../analysis/inheritance.js";
+import { renderHandlerParameters, renderHandlerResultType } from "../../analysis/param-structure.js";
+import { recordTypeTarget, renderBaseType, type TsTypeTarget } from "../../analysis/ts-type.js";
+import { type GirProperty, isConstructableProperty } from "../../gir/property.js";
+import { renderJsDoc } from "../../writer/doc.js";
+import {
+    giNamespaceAlias,
+    hasExposedMethod,
+    isIntrinsicElementClass,
+    signalHandlerName,
+} from "./intrinsic-elements.js";
+
+type IntrinsicElementPropsEntries = {
+    propLines: string[];
+    imports: Map<string, string>;
+    objectPropNames: string[];
+};
+
+type IntrinsicElementScope = {
+    library: Library;
+    klass: GirClass;
+    namespace: GirNamespace;
+};
+
+type IntrinsicElementPropsOptions = IntrinsicElementScope & {
+    isIntrinsicElementAncestor?: (candidate: GirClass) => boolean;
+};
+
+type PropTypeRenderContext = {
+    library: Library;
+    imports: Map<string, string>;
+};
+
+type SignalRenderOptions = {
+    types: PropTypeRenderContext;
+    signal: GirCallable;
+    selfType: string;
+};
+
+type PropEntryCollector = {
+    propLines: string[];
+    imports: Map<string, string>;
+    objectPropNames: string[];
+    acceptProperty: (property: GirProperty) => void;
+    acceptSignal: (signal: GirCallable) => void;
+};
+
+type PropCollectorState = {
+    owner: IntrinsicElementScope;
+    types: PropTypeRenderContext;
+    propLines: string[];
+    objectPropNames: string[];
+    seen: Set<string>;
+};
+
+type InterfacePropsOptions = {
+    library: Library;
+    iface: GirClass;
+    namespace: GirNamespace;
+};
+
+type IntrinsicElementMemberWalk = IntrinsicElementScope & {
+    isIntrinsicElementAncestor: (candidate: GirClass) => boolean;
+    acceptProperty: (property: GirProperty) => void;
+    acceptSignal: (signal: GirCallable) => void;
+};
+
+const appendPropertyLines = (state: PropCollectorState, property: GirProperty, jsName: string): void => {
+    const tsType = renderReactPropType(state.types, property.type, false);
+    const doc = renderJsDoc(property.doc);
+
+    if (isObjectProp(state.owner, property, jsName)) {
+        state.propLines.push(`${doc}${jsName}?: ${tsType} | ReactElement | null | undefined;`);
+        state.objectPropNames.push(jsName);
+
+        return;
+    }
+
+    const isSettable = isConstructableProperty(property);
+
+    if (isSettable) {
+        state.propLines.push(`${doc}${jsName}?: ${tsType} | null | undefined;`);
+    }
+
+    const handlerType = `((value: ${tsType} | null, self: Self) => void) | null | undefined`;
+    state.propLines.push(`${isSettable ? "" : doc}onNotify${upperFirst(jsName)}?: ${handlerType};`);
+};
+
+const acceptCollectorProperty = (state: PropCollectorState, property: GirProperty): void => {
+    if (!property.introspectable) {
+        return;
+    }
+
+    const jsName = toCamelIdentifier(property.name);
+
+    if (state.seen.has(jsName)) {
+        return;
+    }
+
+    state.seen.add(jsName);
+    appendPropertyLines(state, property, jsName);
+};
+
+const acceptCollectorSignal = (state: PropCollectorState, signal: GirCallable): void => {
+    const handlerName = signalHandlerName(signal.name);
+
+    if (state.seen.has(handlerName)) {
+        return;
+    }
+
+    state.seen.add(handlerName);
+    const signature = renderSignalHandler({ types: state.types, signal, selfType: "Self" });
+    state.propLines.push(`${renderJsDoc(signal.doc)}${handlerName}?: (${signature}) | undefined;`);
+};
+
+const createPropEntryCollector = (owner: IntrinsicElementScope): PropEntryCollector => {
+    const { library } = owner;
+    const imports: Map<string, string> = new Map();
+    const types: PropTypeRenderContext = { library, imports };
+
+    const state: PropCollectorState = {
+        owner,
+        types,
+        propLines: [],
+        objectPropNames: [],
+        seen: new Set<string>(),
+    };
+
+    return {
+        propLines: state.propLines,
+        imports,
+        objectPropNames: state.objectPropNames,
+        acceptProperty: (property) => {
+            acceptCollectorProperty(state, property);
+        },
+        acceptSignal: (signal) => {
+            acceptCollectorSignal(state, signal);
+        },
+    };
+};
+
+const buildElementPropsEntries = (options: IntrinsicElementPropsOptions): IntrinsicElementPropsEntries => {
+    const { library, klass, namespace, isIntrinsicElementAncestor = () => false } = options;
+    const collector = createPropEntryCollector({ library, klass, namespace });
+
+    walkIntrinsicElementMembers({
+        library,
+        klass,
+        namespace,
+        isIntrinsicElementAncestor,
+        acceptProperty: collector.acceptProperty,
+        acceptSignal: collector.acceptSignal,
+    });
+
+    return { propLines: collector.propLines, imports: collector.imports, objectPropNames: collector.objectPropNames };
+};
+
+const buildInterfacePropsEntries = (options: InterfacePropsOptions): IntrinsicElementPropsEntries => {
+    const { library, iface, namespace } = options;
+    const collector = createPropEntryCollector({ library, klass: iface, namespace });
+
+    for (const property of iface.properties) {
+        collector.acceptProperty(property);
+    }
+
+    for (const signal of iface.signals) {
+        collector.acceptSignal(signal);
+    }
+
+    return { propLines: collector.propLines, imports: collector.imports, objectPropNames: collector.objectPropNames };
+};
+
+const walkIntrinsicElementMembers = (walk: IntrinsicElementMemberWalk): void => {
+    const { library, klass, namespace, isIntrinsicElementAncestor, acceptProperty, acceptSignal } = walk;
+
+    const visitMembers = (memberClass: GirClass): void => {
+        for (const property of memberClass.properties) {
+            acceptProperty(property);
+        }
+
+        for (const signal of memberClass.signals) {
+            acceptSignal(signal);
+        }
+    };
+
+    const ancestry = { library, namespace };
+    visitMembers(klass);
+
+    forEachAncestor(ancestry, klass, (ancestor) => {
+        visitMembers(ancestor.klass);
+    }, isIntrinsicElementAncestor);
+};
+
+const isGObjectType = (library: Library, ref: TypeId | undefined): boolean => {
+    if (ref === undefined) {
+        return false;
+    }
+
+    const resolved = library.typeFor(ref);
+
+    if (resolved?.kind === "interface") {
+        return true;
+    }
+
+    if (resolved?.kind !== "class") {
+        return false;
+    }
+
+    return isIntrinsicElementClass(resolved.value, resolved.namespace, library);
+};
+
+const isObjectProp = (owner: IntrinsicElementScope, property: GirProperty, jsName: string): boolean => {
+    if (!property.writable || property.constructOnly) {
+        return false;
+    }
+
+    if (!isGObjectType(owner.library, property.type)) {
+        return false;
+    }
+
+    if (jsName === "child" && hasExposedMethod(owner.klass, owner.namespace, owner.library, "set_child")) {
+        return false;
+    }
+
+    return true;
+};
+
+const renderSignalHandler = (options: SignalRenderOptions): string => {
+    const { types, signal, selfType } = options;
+
+    const params = [
+        ...renderHandlerParameters(signal.parameters, (ref, nullable) => renderReactPropType(types, ref, nullable)),
+        `self: ${selfType}`,
+    ];
+
+    const result = renderHandlerResultType({
+        library: types.library,
+        signal,
+        renderType: (ref, nullable) => renderReactPropType(types, ref, nullable),
+        includeCallerAllocated: false,
+        optOut: true,
+    });
+
+    return `(${params.join(", ")}) => ${result}`;
+};
+
+const reactTarget = (context: PropTypeRenderContext): TsTypeTarget =>
+    recordTypeTarget(
+        context.library,
+        (name) => {
+            context.imports.set(name.namespaceName, giNamespaceAlias(name.namespaceName));
+
+            return `${giNamespaceAlias(name.namespaceName)}.${name.typeName}`;
+        },
+        () => {
+            context.imports.set("GObject", giNamespaceAlias("GObject"));
+
+            return `${giNamespaceAlias("GObject")}.Type`;
+        },
+    );
+
+const renderReactPropType = (context: PropTypeRenderContext, ref: TypeId | undefined, isNullable: boolean): string => {
+    const base = renderBaseType(context.library, reactTarget(context), ref);
+
+    return isNullable ? `${base} | null` : base;
+};
+
+export { buildElementPropsEntries, buildInterfacePropsEntries, isObjectProp, reactTarget };

package/src/store/jsx-store.ts

@@ -1,13 +1,21 @@
-import type { JsxNamespaceFile } from "./react/pipeline.js";
+import type { JsxNamespaceFile } from "./jsx/pipeline.js";
+import type { RawFile } from "./store-fs.js";
 import { buildManifest, type StoreOptions, subpathExport, writeStore } from "./store-fs.js";
 
-export type JsxStoreOptions = StoreOptions;
+type JsxStoreOptions = StoreOptions;
 
-export const writeJsxStore = (options: JsxStoreOptions, namespaces: JsxNamespaceFile[], metadata: string): void => {
+const writeJsxStore = (
+    options: JsxStoreOptions,
+    namespaces: JsxNamespaceFile[],
+    metadata: string,
+    fingerprint: RawFile,
+): void => {
     const exportsMap: Record<string, unknown> = {
         "./metadata": subpathExport("metadata"),
     };
+
     const files = [{ fileName: "metadata.ts", source: metadata }];
+
     for (const { directory, source } of namespaces) {
         files.push({ fileName: `${directory}/${directory}.tsx`, source });
         exportsMap[`./${directory}`] = subpathExport(`${directory}/${directory}`);
@@ -23,5 +31,9 @@ export const writeJsxStore = (options: JsxStoreOptions, namespaces: JsxNamespace
             exports: exportsMap,
             peerDependencies: { "@gtkx/gi": "*", "@gtkx/react": "*", react: "*" },
         }),
+        rawFiles: [fingerprint],
+        configEnv: true,
     });
 };
+
+export { writeJsxStore, type JsxStoreOptions };

package/src/store/store-fs.ts

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, mkdtempSync, renameSync, rmSync, symlinkSync, wr
 import { dirname, join, relative } from "node:path";
 import { compileStore } from "./compile-store.js";
 
-export type StoreOptions = {
+type StoreOptions = {
     storeDir: string;
     linkDir: string;
     version: string;
@@ -13,11 +13,6 @@ type StoreFile = {
     source: string;
 };
 
-export const subpathExport = (stem: string): { types: string; default: string } => ({
-    types: `./${stem}.d.ts`,
-    default: `./${stem}.js`,
-});
-
 type Manifest = {
     name: string;
     type: "module";
@@ -34,7 +29,23 @@ type ManifestInput = {
     peerDependencies?: Record<string, string>;
 };
 
-export const buildManifest = (input: ManifestInput): Manifest => {
+type RawFile = { relativePath: string; content: string };
+
+type WriteStoreParams = {
+    storeDir: string;
+    linkDir: string;
+    files: StoreFile[];
+    manifest: Manifest;
+    rawFiles?: RawFile[];
+    configEnv?: boolean;
+};
+
+const subpathExport = (stem: string): { types: string; default: string } => ({
+    types: `./${stem}.d.ts`,
+    default: `./${stem}.js`,
+});
+
+const buildManifest = (input: ManifestInput): Manifest => {
     const manifest: Manifest = {
         name: input.name,
         type: "module",
@@ -42,28 +53,36 @@ export const buildManifest = (input: ManifestInput): Manifest => {
         sideEffects: true,
         exports: { "./package.json": "./package.json", ...input.exports },
     };
+
     if (input.peerDependencies) {
         manifest.peerDependencies = input.peerDependencies;
     }
+
     return manifest;
 };
 
-export const writeStore = (params: WriteStoreParams): void => {
-    const tmp = tempStoreFor(params.storeDir);
+const writeStore = (params: WriteStoreParams): void => {
+    const tmp = createTempStore(params.storeDir);
+
     try {
         for (const file of params.files) {
             writeSourceFile(tmp, file.fileName, file.source);
         }
+
         compileStore({
             storeDir: tmp,
             files: params.files,
             packageName: params.manifest.name,
-            exports: params.manifest.exports,
+            ...(params.configEnv !== undefined && { configEnv: params.configEnv }),
         });
+
         writePackageJson(tmp, params.manifest);
-        for (const raw of params.rawFiles ?? []) {
+        const rawFiles = params.rawFiles ?? [];
+
+        for (const raw of rawFiles) {
             writeFileSync(join(tmp, raw.relativePath), raw.content);
         }
+
         symlinkRelative(join(tmp, "node_modules", ...params.manifest.name.split("/")), tmp);
         swapStore(tmp, params.storeDir, params.linkDir);
     } finally {
@@ -71,14 +90,6 @@ export const writeStore = (params: WriteStoreParams): void => {
     }
 };
 
-type WriteStoreParams = {
-    storeDir: string;
-    linkDir: string;
-    files: StoreFile[];
-    manifest: Manifest;
-    rawFiles?: { relativePath: string; content: string }[];
-};
-
 const writeSourceFile = (storeDir: string, fileName: string, source: string): void => {
     const filePath = join(storeDir, fileName);
     mkdirSync(dirname(filePath), { recursive: true });
@@ -98,15 +109,20 @@ const writePackageJson = (storeDir: string, manifest: Manifest): void => {
 const swapStore = (tmp: string, storeDir: string, visibleLink: string): void => {
     const previous = `${storeDir}.old`;
     rmSync(previous, { recursive: true, force: true });
+
     if (existsSync(storeDir)) {
         renameSync(storeDir, previous);
     }
+
     renameSync(tmp, storeDir);
     rmSync(previous, { recursive: true, force: true });
     symlinkRelative(visibleLink, storeDir);
 };
 
-const tempStoreFor = (storeDir: string): string => {
+const createTempStore = (storeDir: string): string => {
     mkdirSync(dirname(storeDir), { recursive: true });
+
     return mkdtempSync(`${storeDir}.tmp-`);
 };
+
+export { subpathExport, buildManifest, writeStore, type StoreOptions, type RawFile };

package/src/writer/context.ts

@@ -2,7 +2,7 @@ import type { Library } from "../gir/library.js";
 import type { GirNamespace } from "../gir/namespace.js";
 import { ModuleBuilder } from "./module.js";
 
-export class ModuleContext {
+class ModuleContext {
     public module: ModuleBuilder = new ModuleBuilder();
     public namespace: GirNamespace;
     public library: Library;
@@ -25,24 +25,43 @@ export class ModuleContext {
     }
 
     addGObjectBootstrapImports(): void {
-        if (this.namespace.name === "GObject") return;
-        if (this.namespace.name === "GLib") return;
+        if (this.namespace.name === "GObject") {
+            return;
+        }
+
+        if (this.namespace.name === "GLib") {
+            return;
+        }
+
         this.module.imports.addSideEffect("../gobject/overrides/object.js");
         this.module.imports.addSideEffect("../gobject/overrides/value.js");
     }
 
     addCrossNamespaceImport(namespaceName: string): string {
-        if (namespaceName === this.namespace.name) return namespaceName;
+        if (namespaceName === this.namespace.name) {
+            return namespaceName;
+        }
+
         const directory = namespaceName.toLowerCase();
         const isFoundational = directory === "gobject" || directory === "glib";
         const path = isFoundational ? `../${directory}/${directory}.js` : `../${directory}/index.js`;
-        if (!isFoundational) this.module.imports.addSideEffect(path);
+
+        if (!isFoundational) {
+            this.module.imports.addSideEffect(path);
+        }
+
         this.module.imports.addNamespace(path, namespaceName);
+
         return namespaceName;
     }
 
     qualify(namespaceName: string, typeName: string): string {
-        if (namespaceName === this.namespace.name) return typeName;
+        if (namespaceName === this.namespace.name) {
+            return typeName;
+        }
+
         return `${this.addCrossNamespaceImport(namespaceName)}.${typeName}`;
     }
 }
+
+export { ModuleContext };

package/src/writer/doc.ts

@@ -1,11 +1,25 @@
 import { gtkDocToMarkdown } from "./gtk-doc.js";
 
-const escapeCommentTerminators = (doc: string): string => doc.replaceAll("*/", "*\\/");
+const escapeCommentTerminators = (doc: string): string => doc.replaceAll("*/", String.raw`*\/`);
+
+const renderJsDocLines = (lines: string[]): string => {
+    const [single, ...rest] = lines;
+
+    if (single !== undefined && rest.length === 0) {
+        return `/** ${single} */\n`;
+    }
 
-export const renderJsDoc = (doc: string | undefined): string => {
-    if (doc === undefined || doc.length === 0) return "";
-    const lines = escapeCommentTerminators(gtkDocToMarkdown(doc)).split("\n");
-    if (lines.length === 1) return `/** ${lines[0]} */\n`;
     const body = lines.map((line) => (line.length === 0 ? " *" : ` * ${line}`)).join("\n");
+
     return `/**\n${body}\n */\n`;
 };
+
+const renderJsDoc = (doc: string | undefined): string => {
+    if (doc === undefined || doc.length === 0) {
+        return "";
+    }
+
+    return renderJsDocLines(escapeCommentTerminators(gtkDocToMarkdown(doc)).split("\n"));
+};
+
+export { renderJsDoc };

package/src/writer/emit.ts

@@ -1,26 +1,35 @@
-export const indent = (block: string, level: number): string => {
-    if (level <= 0) return block;
-    const prefix = "    ".repeat(level);
+const indent = (block: string, level: number): string => {
+    if (level <= 0) {
+        return block;
+    }
+
+    const prefix = " ".repeat(4).repeat(level);
+
     return block
         .split("\n")
         .map((line) => (line.length === 0 ? line : `${prefix}${line}`))
         .join("\n");
 };
 
-export const renderBlock = (head: string, body: string): string => `${head} {\n${indent(body, 1)}\n}`;
-
-export const renderBraced = (body: string): string => `{\n${indent(body, 1)}\n}`;
+const renderBlock = (head: string, body: string): string => `${head} {\n${indent(body, 1)}\n}`;
+const renderBraced = (body: string): string => `{\n${indent(body, 1)}\n}`;
 
-export const renderBracedOrEmpty = (head: string, body: string): string =>
+const renderBracedOrEmpty = (head: string, body: string): string =>
     body.length === 0 ? `${head} {}` : renderBlock(head, body);
 
-export const indentMembers = (members: string[]): string => members.map((member) => indent(member, 1)).join("\n\n");
+const indentMembers = (members: string[]): string => members.map((member) => indent(member, 1)).join("\n\n");
 
-export const joinArgs = (parts: Array<string | undefined>): string =>
+const joinArgs = (parts: (string | undefined)[]): string =>
     parts.filter((part): part is string => part !== undefined).join(", ");
 
-export const arrayLiteral = (elements: string[]): string => {
-    if (elements.length === 0) return "[]";
+const arrayLiteral = (elements: string[]): string => {
+    if (elements.length === 0) {
+        return "[]";
+    }
+
     const lines = elements.map((element) => `    ${element},`);
+
     return `[\n${lines.join("\n")}\n]`;
 };
+
+export { indent, renderBlock, renderBraced, renderBracedOrEmpty, indentMembers, joinArgs, arrayLiteral };

package/src/writer/gtk-doc.ts

@@ -1,11 +1,8 @@
-import { toCamelCase } from "@gtkx/utils";
+import { camelCase } from "@gtkx/utils";
 
 const CONSTANT_MAP: Record<string, string> = { TRUE: "true", FALSE: "false", NULL: "null" };
-
 const CALLABLE_LINK_KINDS: Set<string> = new Set(["method", "func", "ctor", "vfunc"]);
-
-const SENTINEL = String.fromCharCode(0xe000);
-
+const SENTINEL = String.fromCodePoint(0xE0_00);
 const CODE_BLOCK_OPEN = "|[";
 const CODE_BLOCK_CLOSE = "]|";
 const CODE_LANGUAGE_PATTERN = /^\s*<!--\s*language="([^"]*)"\s*-->/;
@@ -20,55 +17,85 @@ const FUNCTION_REF_PATTERN = /\b([a-z_][a-z0-9_]*)\(\)/g;
 const renderLink = (kind: string, target: string): string => {
     const segments = target.split(/::|[.:]/);
     const lastIndex = segments.length - 1;
-    if (CALLABLE_LINK_KINDS.has(kind) || kind === "property") {
-        segments[lastIndex] = toCamelCase(segments[lastIndex] ?? "");
+
+    if (kind === "property" || CALLABLE_LINK_KINDS.has(kind)) {
+        segments[lastIndex] = camelCase(segments[lastIndex] ?? "");
     }
+
     const symbol = segments.join(".");
+
     return `\`${symbol}${CALLABLE_LINK_KINDS.has(kind) ? "()" : ""}\``;
 };
 
+const trimTrailingNewlines = (value: string): string => {
+    let end = value.length;
+
+    while (end > 0 && value[end - 1] === "\n") {
+        end -= 1;
+    }
+
+    return value.slice(0, end);
+};
+
 const renderCodeFence = (body: string): string => {
-    const languageMatch = body.match(CODE_LANGUAGE_PATTERN);
+    const languageMatch = CODE_LANGUAGE_PATTERN.exec(body);
     const fence = (languageMatch?.[1] ?? "").trim().toLowerCase();
     const rest = languageMatch === null ? body : body.slice(languageMatch[0].length);
-    const code = rest.replace(/^\s+/, "").replace(/\n+$/, "");
+    const code = trimTrailingNewlines(rest.trimStart());
+
     return `\`\`\`${fence}\n${code}\n\`\`\``;
 };
 
 const protectCodeBlocks = (raw: string, protect: (value: string) => string): string => {
     let result = "";
     let cursor = 0;
+
     while (cursor < raw.length) {
         const open = raw.indexOf(CODE_BLOCK_OPEN, cursor);
-        if (open === -1) break;
+
+        if (open === -1) {
+            break;
+        }
+
         const close = raw.indexOf(CODE_BLOCK_CLOSE, open + CODE_BLOCK_OPEN.length);
-        if (close === -1) break;
+
+        if (close === -1) {
+            break;
+        }
+
         result += raw.slice(cursor, open);
         result += protect(renderCodeFence(raw.slice(open + CODE_BLOCK_OPEN.length, close)));
         cursor = close + CODE_BLOCK_CLOSE.length;
     }
+
     return result + raw.slice(cursor);
 };
 
-export const gtkDocToMarkdown = (raw: string): string => {
+const gtkDocToMarkdown = (raw: string): string => {
     const stash: string[] = [];
+
     const protect = (value: string): string => {
-        const token = `${SENTINEL}${stash.length}${SENTINEL}`;
+        const token = `${SENTINEL}${String(stash.length)}${SENTINEL}`;
         stash.push(value);
+
         return token;
     };
 
     let text = protectCodeBlocks(raw, protect);
-    text = text.replace(FENCED_BLOCK_PATTERN, (block) => protect(block));
-    text = text.replace(INLINE_CODE_PATTERN, (span) => protect(span));
-    text = text.replace(LINK_PATTERN, (_match, kind: string, target: string) => protect(renderLink(kind, target)));
-    text = text.replace(CONSTANT_PATTERN, (_match, name: string) => protect(`\`${CONSTANT_MAP[name] ?? name}\``));
-    text = text.replace(TYPE_REF_PATTERN, (_match, name: string) => protect(`\`${name}\``));
-    text = text.replace(PARAM_REF_PATTERN, (_match, name: string) => protect(`\`${name}\``));
-    text = text.replace(FUNCTION_REF_PATTERN, (_match, name: string) => protect(`\`${name}()\``));
+    text = text.replaceAll(FENCED_BLOCK_PATTERN, (block) => protect(block));
+    text = text.replaceAll(INLINE_CODE_PATTERN, (span) => protect(span));
+    text = text.replaceAll(LINK_PATTERN, (_match, kind: string, target: string) => protect(renderLink(kind, target)));
+    text = text.replaceAll(CONSTANT_PATTERN, (_match, name: string) => protect(`\`${CONSTANT_MAP[name] ?? name}\``));
+    text = text.replaceAll(TYPE_REF_PATTERN, (_match, name: string) => protect(`\`${name}\``));
+    text = text.replaceAll(PARAM_REF_PATTERN, (_match, name: string) => protect(`\`${name}\``));
+    text = text.replaceAll(FUNCTION_REF_PATTERN, (_match, name: string) => protect(`\`${name}()\``));
 
     for (let index = stash.length - 1; index >= 0; index -= 1) {
-        text = text.replaceAll(`${SENTINEL}${index}${SENTINEL}`, stash[index] ?? "");
+        const value = stash[index] ?? "";
+        text = text.replaceAll(`${SENTINEL}${String(index)}${SENTINEL}`, () => value);
     }
+
     return text;
 };
+
+export { gtkDocToMarkdown };