@gtkx/codegen 1.0.0-rc.4 → 1.0.0

package/src/docs/render.ts

@@ -1,31 +1,57 @@
 import { pascalCase, sortStringsBy } from "@gtkx/utils";
+import type { GirAnnotations } from "../gir/annotations.js";
 import type { GirClass } from "../gir/class.js";
 import type { GirFunction } from "../gir/function.js";
 import type { Library } from "../gir/library.js";
 import type { GirNamespace } from "../gir/namespace.js";
 import type { GirCallable } from "../gir/parameter.js";
+import type { GirProperty } from "../gir/property.js";
 import type { TypeId } from "../gir/type-id.js";
+import type { JsDocDeprecation, JsDocParam, JsDocSpec } from "../writer/doc-tags.js";
 import { collectInheritedMethods, conflictRename } from "../analysis/inheritance.js";
 import { renderHandlerParameters, renderHandlerResultType } from "../analysis/param-structure.js";
 import { recordTypeTarget, renderBaseType, type TsTypeTarget } from "../analysis/ts-type.js";
-import { dedupeCallables, instanceScope, renderInstanceMethodSignature } from "../store/gi/callables.js";
+import {
+    dedupeCallables,
+    instanceMemberSpec,
+    instanceScope,
+    renderInstanceMethodSignature,
+} from "../store/gi/callables.js";
+import { annotationSpec, handlerSpec, selfHandlerSpec } from "../store/gi/doc-spec.js";
 import { methodExportName } from "../store/gi/method.js";
 import { ModuleContext } from "../writer/context.js";
+import { stripDocMedia } from "../writer/doc-tags.js";
 import { gtkDocToMarkdown } from "../writer/gtk-doc.js";
 
 type SignatureEntry = {
     name: string;
     signature: string;
     doc: string;
+    tags?: JsDocSpec | undefined;
 };
 
 type OriginSignatureEntry = SignatureEntry & { origin: string | undefined };
 
+type MetaDocEntry = {
+    name: string;
+    meta: string;
+    doc: string;
+    tags?: JsDocSpec | undefined;
+};
+
+type PropertyMetaOptions = {
+    type: string;
+    property: GirProperty;
+    accessNotes: string[];
+    origin: string | undefined;
+};
+
 const DOCS_DEFAULT_VALUES: Record<string, string> = { TRUE: "true", FALSE: "false", NULL: "null" };
 const FENCE_LINE = /^\s*(```|~~~)/;
 const HEADING_LINE = /^#{1,5}\s/;
 const LEADING_NAMESPACES = ["Gtk", "Adw"];
 const DOCS_SIGNATURE_NAMESPACE = "$docs";
+const WHITESPACE_RUN = /\s+/g;
 
 const docsTarget = (library: Library): TsTypeTarget =>
     recordTypeTarget(
@@ -63,12 +89,6 @@ const renderDocsSignalHandlerType = (library: Library, signal: GirCallable): str
 
 const docsDefaultValue = (value: string): string => DOCS_DEFAULT_VALUES[value] ?? value;
 
-const stripDocMedia = (markdown: string): string =>
-    markdown
-        .replaceAll(/<picture[\s\S]*?<\/picture>/g, "")
-        .replaceAll(/<video[\s\S]*?(?:<\/video>|\/>)/g, "")
-        .replaceAll(/<img[^>]*>/g, "");
-
 const demoteLine = (line: string, isInFence: boolean): { text: string; isInFence: boolean } => {
     if (FENCE_LINE.test(line)) {
         return { text: line, isInFence: !isInFence };
@@ -102,12 +122,15 @@ const stripMarkdown = (markdown: string): string =>
         .replaceAll(/```[\s\S]*?```/g, " ")
         .replaceAll(/`([^`]*)`/g, "$1")
         .replaceAll(/\[([^[\]]*)\]\([^)]*\)/g, "$1")
-        .replaceAll(/[*_#>]/g, "")
-        .replaceAll(/\s+/g, " ")
+        .replaceAll(/[*#>]/g, "")
+        .replaceAll(WHITESPACE_RUN, " ")
         .trim();
 
+const inlineMarkdown = (doc: string | undefined): string => docMarkdown(doc).replaceAll(WHITESPACE_RUN, " ").trim();
+const plainText = (doc: string | undefined): string => stripMarkdown(docMarkdown(doc));
+
 const firstSentence = (doc: string | undefined): string => {
-    const text = stripMarkdown(docMarkdown(doc));
+    const text = plainText(doc);
 
     if (text.length === 0) {
         return "";
@@ -138,16 +161,102 @@ const implementsLine = (names: string[]): string[] => {
 const joinSections = (sections: string[]): string =>
     `${sections.filter((section) => section.length > 0).join("\n\n")}\n`;
 
-const metaBlock = (name: string, meta: string, doc: string): string => {
-    const lines = [`### \`${name}\``, "", meta];
+const paramNotes = (params: JsDocParam[] | undefined): string[] => {
+    const entries = (params ?? [])
+        .map((param) => ({ name: param.name, text: inlineMarkdown(param.doc) }))
+        .filter((entry) => entry.text.length > 0);
+
+    if (entries.length === 0) {
+        return [];
+    }
+
+    const bullets = entries.map((entry) => `- \`${entry.name}\`: ${entry.text}`);
+
+    return [["**Parameters**", "", ...bullets].join("\n")];
+};
+
+const labelledNote = (label: string, text: string): string[] => (text.length === 0 ? [] : [`${label} ${text}`]);
+
+const deprecationNote = (deprecation: JsDocDeprecation | undefined): string[] => {
+    if (deprecation === undefined) {
+        return [];
+    }
+
+    const since = deprecation.since;
+    const heading = since === undefined ? "**Deprecated.**" : `**Deprecated since ${since}.**`;
+    const text = inlineMarkdown(deprecation.doc);
+    const body = text.length === 0 ? heading : `${heading} ${text}`;
+
+    return [`> ${body}`];
+};
+
+const sinceNote = (since: string | undefined): string[] =>
+    since === undefined || since.length === 0 ? [] : [`_Available since ${since}._`];
+
+const tagNotes = (spec: JsDocSpec | undefined): string[] => {
+    if (spec === undefined) {
+        return [];
+    }
+
+    return [
+        ...paramNotes(spec.params),
+        ...labelledNote("**Returns**", docMarkdown(spec.returns)),
+        ...labelledNote("**Throws**", inlineMarkdown(spec.throws)),
+        ...deprecationNote(spec.deprecated),
+        ...sinceNote(spec.since),
+    ];
+};
+
+const deprecationMeta = (annotations: GirAnnotations): string[] => {
+    if (!annotations.isDeprecated) {
+        return [];
+    }
+
+    const since = annotations.deprecatedSince;
+
+    return [since === undefined ? "deprecated" : `deprecated since ${since}`];
+};
+
+const annotationNotes = (annotations: GirAnnotations): string[] => tagNotes(annotationSpec(annotations));
 
-    if (doc.length > 0) {
-        lines.push("", doc);
+const signalTags = (signal: GirCallable, isSelfIncluded: boolean): JsDocSpec =>
+    isSelfIncluded ? selfHandlerSpec(signal) : handlerSpec(signal, signal.parameters);
+
+const metaBlock = (entry: MetaDocEntry): string => {
+    const lines = [`### \`${entry.name}\``, "", entry.meta];
+
+    for (const note of [entry.doc, ...tagNotes(entry.tags)]) {
+        if (note.length > 0) {
+            lines.push("", note);
+        }
     }
 
     return lines.join("\n");
 };
 
+const sortedMetaBlocks = (entries: MetaDocEntry[]): string[] =>
+    sortStringsBy(entries, (item) => item.name).map((item) => metaBlock(item));
+
+const propertyMetaLine = ({ type, property, accessNotes, origin }: PropertyMetaOptions): string => {
+    const meta = [`\`${type}\``];
+
+    if (property.defaultValue !== undefined) {
+        meta.push(`default \`${docsDefaultValue(property.defaultValue)}\``);
+    }
+
+    if (property.constructOnly) {
+        meta.push("construct-only");
+    }
+
+    meta.push(...accessNotes, ...deprecationMeta(property.annotations));
+
+    if (origin !== undefined) {
+        meta.push(`from \`${origin}\``);
+    }
+
+    return meta.join(" · ");
+};
+
 const signatureBlock = (name: string, signature: string, notes: string[]): string => {
     const lines = [`### \`${name}\``, "", `\`\`\`ts\n${signature}\n\`\`\``];
 
@@ -160,6 +269,9 @@ const signatureBlock = (name: string, signature: string, notes: string[]): strin
     return lines.join("\n");
 };
 
+const signatureEntryBlock = (entry: SignatureEntry, leadingNotes: string[] = []): string =>
+    signatureBlock(entry.name, entry.signature, [...leadingNotes, entry.doc, ...tagNotes(entry.tags)]);
+
 const namespaceOrder = (name: string): string => {
     const index = LEADING_NAMESPACES.indexOf(name);
 
@@ -171,10 +283,7 @@ const docsSignatureContext = (namespace: GirNamespace, library: Library): Module
 
 const originSignatureBlocks = (entries: OriginSignatureEntry[]): string[] =>
     sortStringsBy(entries, (item) => item.name).map((item) =>
-        signatureBlock(item.name, item.signature, [
-            item.origin === undefined ? "" : `From \`${item.origin}\`.`,
-            item.doc,
-        ]),
+        signatureEntryBlock(item, item.origin === undefined ? [] : [`From \`${item.origin}\`.`]),
     );
 
 const classMethodEntries = (library: Library, namespace: GirNamespace, klass: GirClass): SignatureEntry[] => {
@@ -189,9 +298,7 @@ const classMethodEntries = (library: Library, namespace: GirNamespace, klass: Gi
 };
 
 const methodsSectionBlocks = (entries: SignatureEntry[], intro: string): string[] =>
-    entries.length === 0
-        ? []
-        : ["## Methods", intro, ...entries.map((item) => signatureBlock(item.name, item.signature, [item.doc]))];
+    entries.length === 0 ? [] : ["## Methods", intro, ...entries.map((item) => signatureEntryBlock(item))];
 
 const instanceMethodEntries = (
     signatureContext: ModuleContext,
@@ -210,13 +317,7 @@ const instanceMethodEntries = (
 
     for (const method of deduped) {
         const nameOverride = rename(method);
-
-        const rendered = renderInstanceMethodSignature(
-            signatureContext,
-            { ...method, doc: undefined },
-            scope,
-            nameOverride,
-        );
+        const rendered = renderInstanceMethodSignature(signatureContext, method, scope, nameOverride);
 
         if (rendered === undefined) {
             continue;
@@ -224,32 +325,45 @@ const instanceMethodEntries = (
 
         entries.push({
             name: nameOverride ?? methodExportName(method),
-            signature: rendered.trim().replace(/;$/, ""),
+            signature: signatureText(rendered),
             doc: docMarkdown(method.doc),
+            tags: instanceMemberSpec(signatureContext, method, scope),
         });
     }
 
     return sortStringsBy(entries, (entry) => entry.name);
 };
 
+const signatureText = (rendered: string): string => {
+    const start = rendered.startsWith("/**") ? rendered.indexOf("*/") + 2 : 0;
+
+    return rendered.slice(start).trim().replace(/;$/, "");
+};
+
 export {
     renderDocsType,
     renderDocsSignalSignature,
     renderDocsSignalHandlerType,
-    docsDefaultValue,
+    annotationNotes,
+    deprecationMeta,
     docMarkdown,
     firstSentence,
     elementSlug,
     implementsLine,
     joinSections,
-    metaBlock,
+    plainText,
+    propertyMetaLine,
+    signalTags,
     signatureBlock,
+    signatureEntryBlock,
+    sortedMetaBlocks,
     namespaceOrder,
     docsSignatureContext,
     originSignatureBlocks,
     classMethodEntries,
     methodsSectionBlocks,
-    instanceMethodEntries,
+    tagNotes,
+    type MetaDocEntry,
     type SignatureEntry,
     type OriginSignatureEntry,
 };