@gtkx/codegen 1.0.0-rc.4 → 1.0.0

package/src/store/jsx/props.ts

@@ -4,11 +4,13 @@ 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 type { JsDocSpec } from "../../writer/doc.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 { annotationSpec, selfHandlerSpec } from "../gi/doc-spec.js";
 import { getGlibName, giNamespaceAlias, isIntrinsicElementClass, signalHandlerName } from "./intrinsic-elements.js";
 import { isOmittedProp } from "./omitted-props.js";
 
@@ -67,9 +69,18 @@ type IntrinsicElementMemberWalk = IntrinsicElementScope & {
     acceptSignal: (signal: GirCallable) => void;
 };
 
+const notifyDoc = (property: GirProperty, jsName: string, spec: JsDocSpec): string => {
+    const note = `Called with the new value when \`${jsName}\` changes.`;
+    const doc = property.doc;
+    const text = doc === undefined || doc.length === 0 ? note : `${note}\n\n${doc}`;
+
+    return renderJsDoc(text, undefined, spec);
+};
+
 const appendPropertyLines = (state: PropCollectorState, property: GirProperty, jsName: string): void => {
     const tsType = renderReactPropType(state.types, property.type, false);
-    const doc = renderJsDoc(property.doc);
+    const spec = annotationSpec(property.annotations);
+    const doc = renderJsDoc(property.doc, undefined, spec);
 
     if (isObjectProp(state.owner.library, property)) {
         state.propLines.push(`${doc}${jsName}?: ${tsType} | ReactElement | null | undefined;`);
@@ -78,14 +89,15 @@ const appendPropertyLines = (state: PropCollectorState, property: GirProperty, j
         return;
     }
 
-    const isSettable = isConstructableProperty(property);
-
-    if (isSettable) {
+    if (isConstructableProperty(property)) {
         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};`);
+
+    state.propLines.push(
+        `${notifyDoc(property, jsName, spec)}onNotify${upperFirst(jsName)}?: ${handlerType};`,
+    );
 };
 
 const acceptCollectorProperty = (state: PropCollectorState, property: GirProperty): void => {
@@ -112,7 +124,8 @@ const acceptCollectorSignal = (state: PropCollectorState, signal: GirCallable):
 
     state.seen.add(handlerName);
     const signature = renderSignalHandler({ types: state.types, signal, selfType: "Self" });
-    state.propLines.push(`${renderJsDoc(signal.doc)}${handlerName}?: (${signature}) | undefined;`);
+    const doc = renderJsDoc(signal.doc, undefined, selfHandlerSpec(signal));
+    state.propLines.push(`${doc}${handlerName}?: (${signature}) | undefined;`);
 };
 
 const createPropEntryCollector = (owner: IntrinsicElementScope): PropEntryCollector => {
@@ -259,4 +272,4 @@ const renderReactPropType = (context: PropTypeRenderContext, ref: TypeId | undef
     return isNullable ? `${base} | null` : base;
 };
 
-export { buildElementPropsEntries, buildInterfacePropsEntries, isObjectProp, reactTarget };
+export { buildElementPropsEntries, buildInterfacePropsEntries, isObjectProp };

package/src/writer/context.ts

@@ -1,6 +1,6 @@
 import type { Library } from "../gir/library.js";
 import type { GirNamespace } from "../gir/namespace.js";
-import { ModuleBuilder } from "./module.js";
+import { type DeclaredType, ModuleBuilder } from "./module.js";
 
 class ModuleContext {
     public module: ModuleBuilder = new ModuleBuilder();
@@ -55,6 +55,10 @@ class ModuleContext {
         return namespaceName;
     }
 
+    declaredType(owner: string, name: string = owner): DeclaredType {
+        return { name, owner: `${this.namespace.name}.${owner}` };
+    }
+
     qualify(namespaceName: string, typeName: string): string {
         if (namespaceName === this.namespace.name) {
             return typeName;

package/src/writer/doc-tags.ts

@@ -0,0 +1,70 @@
+type JsDocParam = { name: string; doc: string };
+type JsDocDeprecation = { since: string | undefined; doc: string | undefined };
+
+type JsDocSpec = {
+    params?: JsDocParam[];
+    returns?: string | undefined;
+    throws?: string | undefined;
+    deprecated?: JsDocDeprecation | undefined;
+    since?: string | undefined;
+    identifiers?: Map<string, string> | undefined;
+};
+
+type DocConverter = (text: string) => string;
+
+const WHITESPACE_RUN_PATTERN = /\s+/g;
+const PICTURE_PATTERN = /<picture[\s\S]*?<\/picture>/g;
+const VIDEO_PATTERN = /<video[\s\S]*?(?:<\/video>|\/>)/g;
+const IMAGE_PATTERN = /<img[^>]*>/g;
+
+const stripDocMedia = (markdown: string): string =>
+    markdown.replaceAll(PICTURE_PATTERN, "").replaceAll(VIDEO_PATTERN, "").replaceAll(IMAGE_PATTERN, "");
+
+const flatten = (text: string, convert: DocConverter): string =>
+    convert(text).replaceAll(WHITESPACE_RUN_PATTERN, " ").trim();
+
+const paramLines = (params: JsDocParam[] | undefined, convert: DocConverter): string[] =>
+    (params ?? [])
+        .map((param) => ({ name: param.name, text: flatten(param.doc, convert) }))
+        .filter((entry) => entry.text.length > 0)
+        .map((entry) => `@param ${entry.name} ${entry.text}`);
+
+const returnsLines = (returns: string | undefined, convert: DocConverter): string[] => {
+    const text = convert(returns ?? "").trim();
+
+    return text.length === 0 ? [] : `@returns ${text}`.split("\n");
+};
+
+const simpleTagLine = (tag: string, value: string | undefined, convert: DocConverter): string[] => {
+    const text = flatten(value ?? "", convert);
+
+    return text.length === 0 ? [] : [`${tag} ${text}`];
+};
+
+const sinceClause = (since: string | undefined): string =>
+    since === undefined || since.length === 0 ? "" : `Since ${since}.`;
+
+const deprecatedText = (deprecation: JsDocDeprecation, convert: DocConverter): string =>
+    [sinceClause(deprecation.since), flatten(deprecation.doc ?? "", convert)]
+        .filter((part) => part.length > 0)
+        .join(" ");
+
+const deprecatedLine = (deprecation: JsDocDeprecation | undefined, convert: DocConverter): string[] => {
+    if (deprecation === undefined) {
+        return [];
+    }
+
+    const text = deprecatedText(deprecation, convert);
+
+    return [text.length === 0 ? "@deprecated" : `@deprecated ${text}`];
+};
+
+const renderDocTagLines = (spec: JsDocSpec, convert: DocConverter): string[] => [
+    ...paramLines(spec.params, convert),
+    ...returnsLines(spec.returns, convert),
+    ...simpleTagLine("@throws", spec.throws, convert),
+    ...deprecatedLine(spec.deprecated, convert),
+    ...simpleTagLine("@since", spec.since, convert),
+];
+
+export { renderDocTagLines, stripDocMedia, type JsDocDeprecation, type JsDocParam, type JsDocSpec };

package/src/writer/doc.ts

@@ -1,11 +1,15 @@
+import { type JsDocSpec, renderDocTagLines, stripDocMedia } from "./doc-tags.js";
 import { gtkDocToMarkdown } from "./gtk-doc.js";
 
 const escapeCommentTerminators = (doc: string): string => doc.replaceAll("*/", String.raw`*\/`);
 
-const renderJsDocLines = (lines: string[]): string => {
+const convertDoc = (doc: string, identifiers: Map<string, string> | undefined): string =>
+    escapeCommentTerminators(stripDocMedia(gtkDocToMarkdown(doc, identifiers)));
+
+const renderJsDocLines = (lines: string[], isCollapsible: boolean): string => {
     const [single, ...rest] = lines;
 
-    if (single !== undefined && rest.length === 0) {
+    if (isCollapsible && single !== undefined && rest.length === 0) {
         return `/** ${single} */\n`;
     }
 
@@ -14,12 +18,31 @@ const renderJsDocLines = (lines: string[]): string => {
     return `/**\n${body}\n */\n`;
 };
 
-const renderJsDoc = (doc: string | undefined): string => {
-    if (doc === undefined || doc.length === 0) {
-        return "";
+const docLines = (doc: string | undefined, identifiers: Map<string, string> | undefined): string[] =>
+    doc === undefined || doc.length === 0 ? [] : convertDoc(doc, identifiers).split("\n");
+
+const appendNote = (lines: string[], note: string): string[] =>
+    lines.length === 0 ? note.split("\n") : [...lines, "", ...note.split("\n")];
+
+const appendTags = (lines: string[], tagLines: string[]): string[] => {
+    if (lines.length === 0 || tagLines.length === 0) {
+        return [...lines, ...tagLines];
     }
 
-    return renderJsDocLines(escapeCommentTerminators(gtkDocToMarkdown(doc)).split("\n"));
+    return [...lines, "", ...tagLines];
+};
+
+const specLines = (spec: JsDocSpec | undefined): string[] =>
+    spec === undefined ? [] : renderDocTagLines(spec, (text) => convertDoc(text, spec.identifiers));
+
+const renderJsDoc = (doc: string | undefined, note?: string, spec?: JsDocSpec): string => {
+    const described = docLines(doc, spec?.identifiers);
+    const withNote = note === undefined ? described : appendNote(described, note);
+    const tagLines = specLines(spec);
+    const lines = appendTags(withNote, tagLines);
+
+    return lines.length === 0 ? "" : renderJsDocLines(lines, tagLines.length === 0);
 };
 
+export { type JsDocSpec } from "./doc-tags.js";
 export { renderJsDoc };

package/src/writer/gtk-doc.ts

@@ -1,7 +1,7 @@
 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 CALLABLE_LINK_KINDS: Set<string> = new Set(["method", "func", "ctor", "vfunc", "id"]);
 const SENTINEL = String.fromCodePoint(0xE0_00);
 const CODE_BLOCK_OPEN = "|[";
 const CODE_BLOCK_CLOSE = "]|";
@@ -9,10 +9,23 @@ const CODE_LANGUAGE_PATTERN = /^\s*<!--\s*language="([^"]*)"\s*-->/;
 const FENCED_BLOCK_PATTERN = /```[\s\S]*?```/g;
 const INLINE_CODE_PATTERN = /`[^`\n]*`/g;
 const LINK_PATTERN = /\[(\w+)@([\w.:%#-]+)\]/g;
-const CONSTANT_PATTERN = /(?<!\w)%(\w+)/g;
-const TYPE_REF_PATTERN = /(?<!\w)#(\w+)/g;
+const CONSTANT_PATTERN = /(?<![\w\\])%(\w+)/g;
+const ESCAPED_CONSTANT_PATTERN = /\\%/g;
+const TYPE_REF_PATTERN = /(?<!\w)#(\w+)(::[\w-]+|:[\w-]+)?/g;
 const PARAM_REF_PATTERN = /(?<!\w)@(\w+)/g;
 const FUNCTION_REF_PATTERN = /\b([a-z_][a-z0-9_]*)\(\)/g;
+const HTML_COMMENT_PATTERN = /<!--[\s\S]*?-->/g;
+const DOCBOOK_TAG_PATTERN = /<\/?(?:itemizedlist|listitem|para|literal|link|informalexample|programlisting)[\s>]/;
+const DOCBOOK_LISTING_OPEN = "<programlisting>";
+const DOCBOOK_LISTING_CLOSE = "</programlisting>";
+const DOCBOOK_EXAMPLE_PATTERN = /<\/?informalexample>\s*/g;
+const DOCBOOK_ITEM_OPEN_PATTERN = /<listitem>\s*(?:<para>\s*)?/g;
+const DOCBOOK_ITEM_CLOSE_PATTERN = /(?:<\/para>\s*)?<\/listitem>\s*/g;
+const DOCBOOK_LINK_PATTERN = /<link\s+linkend="[^"]*">([\s\S]*?)<\/link>/g;
+const DOCBOOK_LITERAL_PATTERN = /<literal>([\s\S]*?)<\/literal>/g;
+const DOCBOOK_LIST_PATTERN = /<\/?itemizedlist>\s*/g;
+const DOCBOOK_PARA_PATTERN = /<\/?para>\s*/g;
+const BLANK_LINE_RUN_PATTERN = /\n{3,}/g;
 
 const renderLink = (kind: string, target: string): string => {
     const segments = target.split(/::|[.:]/);
@@ -27,6 +40,17 @@ const renderLink = (kind: string, target: string): string => {
     return `\`${symbol}${CALLABLE_LINK_KINDS.has(kind) ? "()" : ""}\``;
 };
 
+const renderTypeRef = (name: string, member: string | undefined): string => {
+    if (member === undefined) {
+        return `\`${name}\``;
+    }
+
+    return renderLink(member.startsWith("::") ? "signal" : "property", `${name}${member}`);
+};
+
+const renderParamRef = (name: string, identifiers: Map<string, string> | undefined): string =>
+    `\`${identifiers?.get(name) ?? name}\``;
+
 const trimTrailingNewlines = (value: string): string => {
     let end = value.length;
 
@@ -46,32 +70,69 @@ const renderCodeFence = (body: string): string => {
     return `\`\`\`${fence}\n${code}\n\`\`\``;
 };
 
-const protectCodeBlocks = (raw: string, protect: (value: string) => string): string => {
+const renderListing = (code: string): string => `\n\`\`\`\n${code.trim()}\n\`\`\`\n`;
+
+const replaceDocBookTags = (text: string): string =>
+    replaceDelimited(text, [DOCBOOK_LISTING_OPEN, DOCBOOK_LISTING_CLOSE], renderListing)
+        .replaceAll(DOCBOOK_EXAMPLE_PATTERN, "\n")
+        .replaceAll(DOCBOOK_ITEM_OPEN_PATTERN, "\n- ")
+        .replaceAll(DOCBOOK_ITEM_CLOSE_PATTERN, "\n")
+        .replaceAll(DOCBOOK_LINK_PATTERN, (_match, label: string) => label)
+        .replaceAll(DOCBOOK_LITERAL_PATTERN, (_match, literal: string) => `\`${literal}\``)
+        .replaceAll(DOCBOOK_LIST_PATTERN, "\n\n")
+        .replaceAll(DOCBOOK_PARA_PATTERN, "\n\n");
+
+const docBookToMarkdown = (text: string): string => {
+    if (!DOCBOOK_TAG_PATTERN.test(text)) {
+        return text;
+    }
+
+    return replaceDocBookTags(text).replaceAll(BLANK_LINE_RUN_PATTERN, "\n\n").trim();
+};
+
+const replaceDelimited = (raw: string, bounds: [string, string], render: (body: string) => string): string => {
+    const [open, close] = bounds;
     let result = "";
     let cursor = 0;
 
     while (cursor < raw.length) {
-        const open = raw.indexOf(CODE_BLOCK_OPEN, cursor);
+        const start = raw.indexOf(open, cursor);
 
-        if (open === -1) {
+        if (start === -1) {
             break;
         }
 
-        const close = raw.indexOf(CODE_BLOCK_CLOSE, open + CODE_BLOCK_OPEN.length);
+        const end = raw.indexOf(close, start + open.length);
 
-        if (close === -1) {
+        if (end === -1) {
             break;
         }
 
-        result += raw.slice(cursor, open);
-        result += protect(renderCodeFence(raw.slice(open + CODE_BLOCK_OPEN.length, close)));
-        cursor = close + CODE_BLOCK_CLOSE.length;
+        result += raw.slice(cursor, start);
+        result += render(raw.slice(start + open.length, end));
+        cursor = end + close.length;
     }
 
     return result + raw.slice(cursor);
 };
 
-const gtkDocToMarkdown = (raw: string): string => {
+const protectCodeBlocks = (raw: string, protect: (value: string) => string): string =>
+    replaceDelimited(raw, [CODE_BLOCK_OPEN, CODE_BLOCK_CLOSE], (body) => protect(renderCodeFence(body)));
+
+const stripHtmlComments = (text: string): string => {
+    let current = text;
+    let previous = "";
+
+    while (current !== previous) {
+        previous = current;
+        current = current.replaceAll(HTML_COMMENT_PATTERN, "");
+    }
+
+    return current;
+};
+
+// eslint-disable-next-line gtkx/no-library-prefix
+const gtkDocToMarkdown = (raw: string, identifiers?: Map<string, string>): string => {
     const stash: string[] = [];
 
     const protect = (value: string): string => {
@@ -81,14 +142,20 @@ const gtkDocToMarkdown = (raw: string): string => {
         return token;
     };
 
-    let text = protectCodeBlocks(raw, protect);
+    let text = protectCodeBlocks(docBookToMarkdown(raw), protect);
     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(ESCAPED_CONSTANT_PATTERN, "%");
+
+    text = text.replaceAll(TYPE_REF_PATTERN, (_match, name: string, member: string | undefined) =>
+        protect(renderTypeRef(name, member)),
+    );
+
+    text = text.replaceAll(PARAM_REF_PATTERN, (_match, name: string) => protect(renderParamRef(name, identifiers)));
     text = text.replaceAll(FUNCTION_REF_PATTERN, (_match, name: string) => protect(`\`${name}()\``));
+    text = stripHtmlComments(text);
 
     for (let index = stash.length - 1; index >= 0; index -= 1) {
         const value = stash[index] ?? "";

package/src/writer/module.ts

@@ -1,13 +1,32 @@
 import { ImportsBuilder } from "./imports.js";
 
+type DeclaredType = {
+    name: string;
+    owner: string;
+};
+
 class ModuleBuilder {
     private bindings: string[] = [];
     private bindingNames: Set<string> = new Set();
     private hoistedDescriptors: Map<string, string> = new Map();
     private declarations: string[] = [];
+    private declaredTypes: Map<string, string> = new Map();
     private registrations: string[] = [];
     public imports: ImportsBuilder = new ImportsBuilder();
 
+    private claimTypeName(declared: DeclaredType): void {
+        const owner = this.declaredTypes.get(declared.name);
+
+        if (owner !== undefined && owner !== declared.owner) {
+            throw new Error(
+                `The generated type '${declared.name}' is declared for both ${owner} and ${declared.owner}. ` +
+                "Rename one of them, or drop the namespace from the configuration.",
+            );
+        }
+
+        this.declaredTypes.set(declared.name, declared.owner);
+    }
+
     appendBinding(code: string, name?: string): void {
         if (name !== undefined) {
             if (this.bindingNames.has(name)) {
@@ -34,7 +53,11 @@ class ModuleBuilder {
         return name;
     }
 
-    appendDeclaration(code: string): void {
+    appendDeclaration(code: string, declared?: DeclaredType): void {
+        if (declared !== undefined) {
+            this.claimTypeName(declared);
+        }
+
         this.declarations.push(code);
     }
 
@@ -66,4 +89,4 @@ class ModuleBuilder {
     }
 }
 
-export { ModuleBuilder };
+export { type DeclaredType, ModuleBuilder };