@gtkx/codegen 1.0.0-rc.3 → 1.0.0

package/src/jsx.ts

@@ -1,4 +1,5 @@
 import type { Library } from "./gir/library.js";
+import type { StoreOptions } from "./store/store-fs.js";
 import {
     computeJsxFingerprint,
     FINGERPRINT_FILENAME,
@@ -6,70 +7,69 @@ import {
     jsxStoreFreshness,
 } from "./fingerprint.js";
 import { type ModuleExport, readBuiltinElements } from "./react/element-config.js";
-import { type JsxStoreOptions, writeJsxStore } from "./store/jsx-store.js";
-import { mergeOmitProps, type OmittedProps } from "./store/jsx/omitted-props.js";
+import { writeJsxStore } from "./store/jsx-store.js";
+import { ELEMENTS_FILENAME, renderGeneratedElements } from "./store/jsx/generated-elements.js";
+import { mergeOmittedProps, type OmittedProps } from "./store/jsx/omitted-props.js";
 import { generateJsxFiles } from "./store/jsx/pipeline.js";
 
 type RunJsxCodegenOptions = {
     getLibrary: () => Library;
-    jsx: JsxStoreOptions;
+    jsx: StoreOptions;
     giStoreDir: string;
     reactSubexports: string[];
     userComponents: Record<string, ModuleExport>;
     userLazyElements: string[];
     userProps: Record<string, ModuleExport>;
-    userOmitProps: OmittedProps;
-    giRegenerated: boolean;
-    force: boolean;
+    userOmittedProps: OmittedProps;
+    isGiRegenerated: boolean;
+    isForced: boolean;
 };
 
 type RunJsxCodegenResult = {
-    regenerated: boolean;
+    isRegenerated: boolean;
     intrinsicElementCount: number;
 };
 
-/**
- * Generates the `@gtkx/jsx` store, reading the framework's built-in element config from the freshly
- * linked `@gtkx/react` and layering the project's own element config over it. This is the react-importing
- * half of codegen: it must run only after the gi store has been written and linked.
- */
 const runJsxCodegen = async (options: RunJsxCodegenOptions): Promise<RunJsxCodegenResult> => {
     const builtin = await readBuiltinElements(options.reactSubexports, options.giStoreDir);
     const components = { ...builtin.components, ...options.userComponents };
     const lazyElements = [...builtin.lazyElements, ...options.userLazyElements];
     const props = { ...builtin.props, ...options.userProps };
-    const omitProps = mergeOmitProps(builtin.omitProps, options.userOmitProps);
+    const omittedProps = mergeOmittedProps(builtin.omittedProps, options.userOmittedProps);
 
     const fingerprintInput: JsxFingerprintInput = {
         reactVersion: options.jsx.version,
         components,
         lazyElements,
         props,
-        omitProps,
+        omittedProps,
     };
 
-    if (!options.force && !options.giRegenerated) {
-        const { fresh, intrinsicElementCount } = jsxStoreFreshness(options.jsx.storeDir, fingerprintInput);
+    if (!options.isForced && !options.isGiRegenerated) {
+        const { isFresh, intrinsicElementCount } = jsxStoreFreshness(options.jsx.storeDir, fingerprintInput);
 
-        if (fresh) {
-            return { regenerated: false, intrinsicElementCount };
+        if (isFresh) {
+            return { isRegenerated: false, intrinsicElementCount };
         }
     }
 
-    const { namespaces, metadata, intrinsicElementCount } = generateJsxFiles(options.getLibrary(), {
+    const { namespaces, metadata, intrinsicElementCount, elements } = generateJsxFiles(options.getLibrary(), {
         reactSubexports: options.reactSubexports,
         components,
         lazyElements,
         props,
-        omitProps,
+        omittedProps,
     });
 
-    writeJsxStore(options.jsx, namespaces, metadata, {
-        relativePath: FINGERPRINT_FILENAME,
-        content: `${JSON.stringify(computeJsxFingerprint(fingerprintInput, intrinsicElementCount), null, 2)}\n`,
-    });
+    writeJsxStore(options.jsx, namespaces, metadata, [
+        {
+            relativePath: FINGERPRINT_FILENAME,
+            content: `${JSON.stringify(computeJsxFingerprint(fingerprintInput, intrinsicElementCount), null, 2)}\n`,
+        },
+        { relativePath: ELEMENTS_FILENAME, content: renderGeneratedElements(elements) },
+    ]);
 
-    return { regenerated: true, intrinsicElementCount };
+    return { isRegenerated: true, intrinsicElementCount };
 };
 
-export { runJsxCodegen, type RunJsxCodegenOptions, type RunJsxCodegenResult };
+export { runJsxCodegen };

package/src/khronos/args.ts

@@ -1,6 +1,6 @@
 import { toCamelIdentifier } from "@gtkx/utils";
 import type { GlCommand, GlParam } from "./model.js";
-import type { CommandPlan, GlScalar, ParamPlan } from "./plan.js";
+import type { CommandPlan, GlScalar, ParamPlan, ReturnPlan } from "./plan.js";
 import {
     tArray,
     tBoolean,
@@ -15,14 +15,14 @@ import {
 import { paramPairAt } from "./param-pair.js";
 
 type InArg = {
-    out: false;
+    isOut: false;
     name: string;
     tsType: string;
     descriptor: string;
 };
 
 type OutArg = {
-    out: true;
+    isOut: true;
     cellName: string;
     seed: string;
     tsType: string;
@@ -31,7 +31,7 @@ type OutArg = {
 };
 
 type PlannedArg = InArg | OutArg;
-type OutArgCell = Pick<OutArg, "out" | "cellName" | "paramIndex">;
+type OutArgCell = Pick<OutArg, "isOut" | "cellName" | "paramIndex">;
 type OutArgFields = Pick<OutArg, "seed" | "tsType" | "descriptor">;
 
 type OutArgFieldsOptions = {
@@ -52,7 +52,30 @@ type BuildArgOptions = {
 const OUT_PLAN_KINDS: Set<string> = new Set(["ref-out", "ref-array-out", "ref-fixed-out", "string-out"]);
 
 const scalarAliasOrGroup = (scalar: GlScalar, group: string | undefined): string =>
-    group !== undefined && scalar.groupBearing === true ? group : scalar.tsAlias;
+    group !== undefined && scalar.isGroupBearing === true ? group : scalar.tsAlias;
+
+const returnPlanTsType = (plan: ReturnPlan, group: string | undefined): string => {
+    switch (plan.kind) {
+        case "void": {
+            return "void";
+        }
+        case "scalar": {
+            return scalarAliasOrGroup(plan.scalar, group);
+        }
+        case "boolean": {
+            return "boolean";
+        }
+        case "string": {
+            return "string";
+        }
+        case "sync": {
+            return "GLsync";
+        }
+        case "opaque-pointer": {
+            return "GLpointer";
+        }
+    }
+};
 
 const paramIndexByName = (command: GlCommand, name: string): number => {
     const index = command.params.findIndex((param) => param.name === name);
@@ -71,7 +94,7 @@ const arrayInTsType = (scalar: GlScalar, group: string | undefined): string => {
 };
 
 const inArg = (name: string, tsType: string, descriptor: string): InArg => ({
-    out: false,
+    isOut: false,
     name,
     tsType,
     descriptor,
@@ -141,7 +164,7 @@ const outArgFields = (options: OutArgFieldsOptions): OutArgFields => {
 
             return {
                 seed: `const ${cellName} = { value: new Array<number>(${lenIdentifier}).fill(0) };`,
-                tsType: `${track(plan.scalar.tsAlias)}[]`,
+                tsType: `${track(scalarAliasOrGroup(plan.scalar, param.group))}[]`,
                 descriptor: tRef(tSizedArray(plan.scalar.descriptor, sizeIndex)),
             };
         }
@@ -182,14 +205,14 @@ const buildOutArg = (options: BuildArgOptions, track: (alias: string) => string)
     }
 
     const cellName = `out${String(outIndex)}`;
-    const cell: OutArgCell = { out: true, cellName, paramIndex: index };
+    const cell: OutArgCell = { isOut: true, cellName, paramIndex: index };
 
     return { ...cell, ...outArgFields({ command, plan, param, cellName, track }) };
 };
 
 const isOutPlan = (plan: ParamPlan): boolean => OUT_PLAN_KINDS.has(plan.kind);
-const isInArg = (arg: PlannedArg): arg is InArg => !arg.out;
-const isOutArg = (arg: PlannedArg): arg is OutArg => arg.out;
+const isInArg = (arg: PlannedArg): arg is InArg => !arg.isOut;
+const isOutArg = (arg: PlannedArg): arg is OutArg => arg.isOut;
 
 const buildArg = (options: BuildArgOptions, name: string, track: (alias: string) => string): PlannedArg =>
     isOutPlan(options.plan) ? buildOutArg(options, track) : buildInArg(options, name, track);
@@ -203,7 +226,7 @@ const trackInto =
         };
 
 const planArgs = (
-    plan: CommandPlan & { ok: true },
+    plan: CommandPlan & { isOk: true },
     usedTypes: Set<string>,
 ): { args: PlannedArg[]; ins: InArg[]; outs: OutArg[] } => {
     const track = trackInto(usedTypes);
@@ -230,7 +253,7 @@ const planArgs = (
 };
 
 const scalarPrefixArg = (
-    plan: CommandPlan & { ok: true },
+    plan: CommandPlan & { isOk: true },
     index: number,
     track: (alias: string) => string,
 ): InArg | undefined => {
@@ -251,7 +274,7 @@ const scalarPrefixArg = (
     );
 };
 
-const scalarPrefixArgs = (plan: CommandPlan & { ok: true }, usedTypes: Set<string>): InArg[] | undefined => {
+const scalarPrefixArgs = (plan: CommandPlan & { isOk: true }, usedTypes: Set<string>): InArg[] | undefined => {
     const track = trackInto(usedTypes);
     const prefix: InArg[] = [];
 
@@ -268,4 +291,4 @@ const scalarPrefixArgs = (plan: CommandPlan & { ok: true }, usedTypes: Set<strin
     return prefix;
 };
 
-export { scalarAliasOrGroup, trackInto, planArgs, scalarPrefixArgs, type InArg, type OutArg };
+export { returnPlanTsType, scalarAliasOrGroup, trackInto, planArgs, scalarPrefixArgs, type InArg, type OutArg };

package/src/khronos/doc-context.ts

@@ -0,0 +1,62 @@
+import { sortStrings } from "@gtkx/utils";
+import type { GlExtensionAttribution, GlExtensionIndex } from "./extensions.js";
+import type { GlEnum, GlRegistry, GlType } from "./model.js";
+import type { CommandPlan } from "./plan.js";
+
+type GlDocEnumRow = {
+    token: GlEnum;
+    exportName: string;
+};
+
+type GlDocContext = {
+    registryComment?: string;
+    kinds: Map<string, string>;
+    types: Map<string, GlType>;
+    aliasTargets: Map<string, string[]>;
+    extensionCommands: Map<string, GlExtensionAttribution[]>;
+    extensionEnums: Map<string, GlExtensionAttribution[]>;
+    bitmaskGroups: Set<string>;
+    emittedCommands: Set<string>;
+    groupMembers: Map<string, string[]>;
+};
+
+type BuildDocContextOptions = {
+    registry: GlRegistry;
+    extensions: GlExtensionIndex;
+    plans: (CommandPlan & { isOk: true })[];
+    enumRows: GlDocEnumRow[];
+};
+
+const buildGroupMembers = (rows: GlDocEnumRow[]): Map<string, string[]> => {
+    const members: Map<string, string[]> = new Map();
+
+    for (const row of rows) {
+        for (const group of row.token.groups) {
+            members.set(group, [...(members.get(group) ?? []), row.exportName]);
+        }
+    }
+
+    for (const [group, names] of members) {
+        members.set(group, sortStrings(names));
+    }
+
+    return members;
+};
+
+const buildDocContext = (options: BuildDocContextOptions): GlDocContext => {
+    const { registry, extensions, plans, enumRows } = options;
+
+    return {
+        ...(registry.comment !== undefined && { registryComment: registry.comment }),
+        kinds: registry.kinds,
+        types: registry.types,
+        aliasTargets: registry.aliasTargets,
+        extensionCommands: extensions.commands,
+        extensionEnums: extensions.enums,
+        bitmaskGroups: registry.bitmaskGroups,
+        emittedCommands: new Set(plans.map((plan) => plan.command.name)),
+        groupMembers: buildGroupMembers(enumRows),
+    };
+};
+
+export { buildDocContext, type GlDocContext };

package/src/khronos/extensions.ts

@@ -0,0 +1,85 @@
+import { sortStrings } from "@gtkx/utils";
+import type { GlExtension, GlInterfaceBlock, GlRegistry } from "./model.js";
+import type { GlSelection } from "./select.js";
+
+type GlExtensionAttribution = {
+    name: string;
+    notes: string[];
+};
+
+type GlExtensionIndex = {
+    commands: Map<string, GlExtensionAttribution[]>;
+    enums: Map<string, GlExtensionAttribution[]>;
+};
+
+type PendingIndex = Map<string, Map<string, string[]>>;
+
+type PendingExtensionIndex = {
+    commands: PendingIndex;
+    enums: PendingIndex;
+};
+
+const SUPPORTED_APIS: Set<string> = new Set(["gl", "glcore"]);
+
+const isExtensionSupported = (extension: GlExtension): boolean =>
+    extension.supported.some((api) => SUPPORTED_APIS.has(api));
+
+const isBlockIncluded = (block: GlInterfaceBlock, selection: GlSelection): boolean =>
+    block.kind === "require" &&
+    (block.api === undefined || block.api === selection.api) &&
+    (block.profile === undefined || block.profile === selection.profile);
+
+const blockNotes = (extension: GlExtension, block: GlInterfaceBlock): string[] => [
+    ...(extension.comment === undefined ? [] : [extension.comment]),
+    ...(block.comment === undefined ? [] : [block.comment]),
+];
+
+const appendMembers = (index: PendingIndex, names: string[], extension: string, notes: string[]): void => {
+    for (const name of names) {
+        const byExtension = index.get(name) ?? new Map<string, string[]>();
+        byExtension.set(extension, [...(byExtension.get(extension) ?? []), ...notes]);
+        index.set(name, byExtension);
+    }
+};
+
+const indexExtension = (index: PendingExtensionIndex, extension: GlExtension, selection: GlSelection): void => {
+    for (const block of extension.blocks) {
+        if (!isBlockIncluded(block, selection)) {
+            continue;
+        }
+
+        const notes = blockNotes(extension, block);
+        appendMembers(index.commands, block.commands, extension.name, notes);
+        appendMembers(index.enums, block.enums, extension.name, notes);
+    }
+};
+
+const attributionsFor = (byExtension: Map<string, string[]>): GlExtensionAttribution[] =>
+    sortStrings(byExtension.keys()).map((name) => ({
+        name,
+        notes: [...new Set(byExtension.get(name))],
+    }));
+
+const finalizeIndex = (pending: PendingIndex): Map<string, GlExtensionAttribution[]> => {
+    const index: Map<string, GlExtensionAttribution[]> = new Map();
+
+    for (const [name, byExtension] of pending) {
+        index.set(name, attributionsFor(byExtension));
+    }
+
+    return index;
+};
+
+const buildExtensionIndex = (registry: GlRegistry, selection: GlSelection): GlExtensionIndex => {
+    const pending: PendingExtensionIndex = { commands: new Map(), enums: new Map() };
+
+    for (const extension of registry.extensions) {
+        if (isExtensionSupported(extension)) {
+            indexExtension(pending, extension, selection);
+        }
+    }
+
+    return { commands: finalizeIndex(pending.commands), enums: finalizeIndex(pending.enums) };
+};
+
+export { buildExtensionIndex, type GlExtensionAttribution, type GlExtensionIndex };

package/src/khronos/jsdoc.ts

@@ -1,24 +1,52 @@
 import { toCamelIdentifier } from "@gtkx/utils";
 import type { InArg, OutArg } from "./args.js";
-import type { GlCommand } from "./model.js";
-import type { ReturnPlan } from "./plan.js";
+import type { GlDocContext } from "./doc-context.js";
+import type { GlCommand, GlGlx, GlParam } from "./model.js";
+import type { CommandPlan, ParamPlan, ReturnPlan } from "./plan.js";
+import type { GlSymbolProvenance } from "./select.js";
+import { returnPlanTsType, scalarAliasOrGroup } from "./args.js";
+import {
+    asSentence,
+    backtick,
+    backtickList,
+    commandExportName,
+    kindDescriptions,
+    metadataNotes,
+    type MetadataNotesOptions,
+    provenanceLines,
+} from "./notes.js";
+import { paramPairAt } from "./param-pair.js";
+
+type OkPlan = CommandPlan & { isOk: true };
+
+type ParamPair = {
+    param: GlParam;
+    paramPlan: ParamPlan;
+};
 
 type CommandJsDocOptions = {
-    command: GlCommand;
-    feature: string;
+    plan: OkPlan;
+    provenance: GlSymbolProvenance;
     ins: InArg[];
     outs: OutArg[];
-    returnPlan: ReturnPlan;
+    docs: GlDocContext;
 };
 
-type SingularJsDocOptions = {
-    commandName: string;
-    feature: string;
+type DerivedJsDocOptions = {
+    command: GlCommand;
+    provenance: GlSymbolProvenance;
     summary: string;
     body: string[];
+    docs: GlDocContext;
 };
 
-const REFPAGES_BASE = "https://registry.khronos.org/OpenGL-Refpages/gl4/html";
+const GROUPED_PLAN_KINDS: Set<string> = new Set(["scalar", "array-in", "ref-out", "ref-array-out"]);
+const LENGTHLESS_PLAN_KINDS: Set<string> = new Set(["byte-offset", "byte-offset-array", "ref-out"]);
+
+const OFFSET_NOTES: Map<string, string> = new Map([
+    ["byte-offset", "byte offset into the bound buffer"],
+    ["byte-offset-array", "byte offsets into the bound buffer"],
+]);
 
 const formatPrototype = (command: GlCommand): string => {
     const params = command.params
@@ -28,87 +56,155 @@ const formatPrototype = (command: GlCommand): string => {
     return `${command.returnCType} ${command.name}(${params})`;
 };
 
-const inParamDocLine = (command: GlCommand, arg: InArg): string => {
-    const param = command.params.find((candidate) => toCamelIdentifier(candidate.name) === arg.name);
+const glxLine = (glx: GlGlx): string => {
+    const opcode = ` * GLX ${glx.type} opcode ${glx.opcode}.`;
 
-    if (param === undefined) {
-        return ` * @param ${arg.name}`;
-    }
+    return glx.comment === undefined ? opcode : `${opcode} ${asSentence(glx.comment)}`;
+};
 
-    const notes: string[] = [`\`${param.cType}\``];
+const aliasLine = (aliases: string[]): string => ` * Also known as ${backtickList(aliases)}.`;
 
-    if (param.group !== undefined) {
-        notes.push(`group \`${param.group}\``);
-    }
+const vectorFormLines = (command: GlCommand, docs: GlDocContext): string[] => {
+    const target = command.vecEquiv;
 
-    if (param.len !== undefined) {
-        notes.push(`length \`${param.len}\``);
+    if (target === undefined || !docs.emittedCommands.has(target)) {
+        return [];
     }
 
-    if (param.objectClass !== undefined) {
-        notes.push(`object class \`${param.objectClass}\``);
-    }
+    return [` * Vector form: ${backtick(commandExportName(target))}.`];
+};
 
-    return ` * @param ${arg.name} - ${notes.join(", ")}`;
+const commandNotes = (command: GlCommand, docs: GlDocContext): string[] => {
+    const aliases = docs.aliasTargets.get(command.name) ?? [];
+
+    return [
+        ...(command.comment === undefined ? [] : [` * Registry note: ${command.comment}`]),
+        ...(aliases.length > 0 ? [aliasLine(aliases)] : []),
+        ...vectorFormLines(command, docs),
+        ...(command.glx === undefined ? [] : [glxLine(command.glx)]),
+    ];
 };
 
-const outMember = (command: GlCommand, out: OutArg): string => {
-    const param = command.params[out.paramIndex];
+const isGroupFolded = (plan: ParamPlan | ReturnPlan, group: string): boolean =>
+    GROUPED_PLAN_KINDS.has(plan.kind) &&
+    "scalar" in plan &&
+    scalarAliasOrGroup(plan.scalar, group) !== plan.scalar.tsAlias;
 
-    if (param === undefined) {
-        throw new Error(`Output parameter index ${String(out.paramIndex)} out of range on ${command.name}`);
-    }
+const groupEntry = (param: GlParam, paramPlan: ParamPlan): { group?: string } =>
+    param.group === undefined || isGroupFolded(paramPlan, param.group) ? {} : { group: param.group };
+
+const lengthEntry = (param: GlParam, paramPlan: ParamPlan): { len?: string } =>
+    param.len === undefined || LENGTHLESS_PLAN_KINDS.has(paramPlan.kind) ? {} : { len: param.len };
+
+const paramShape = (param: GlParam, paramPlan: ParamPlan, type: string): MetadataNotesOptions => {
+    const note = OFFSET_NOTES.get(paramPlan.kind);
+
+    return {
+        type,
+        ...groupEntry(param, paramPlan),
+        ...lengthEntry(param, paramPlan),
+        ...(param.objectClass !== undefined && { objectClass: param.objectClass }),
+        ...(note !== undefined && { note }),
+        kinds: param.kinds,
+    };
+};
+
+const returnShape = (plan: OkPlan): MetadataNotesOptions => {
+    const { command, returnPlan } = plan;
+    const group = command.returnGroup;
 
-    return `\`${param.name}\` (\`${param.cType}\`)`;
+    return {
+        type: returnPlanTsType(returnPlan, group),
+        ...(group !== undefined && !isGroupFolded(returnPlan, group) && { group }),
+        ...(command.returnObjectClass !== undefined && { objectClass: command.returnObjectClass }),
+        kinds: command.returnKinds,
+    };
 };
 
-const returnsDocLine = (command: GlCommand, returnPlan: ReturnPlan, outs: OutArg[]): string | undefined => {
-    const members: string[] = [];
+const paramPairFor = (plan: OkPlan, argName: string): ParamPair | undefined => {
+    const index = plan.command.params.findIndex((candidate) => toCamelIdentifier(candidate.name) === argName);
+    const { param, paramPlan } = paramPairAt(plan, index);
 
-    if (returnPlan.kind !== "void") {
-        members.push(`\`${command.returnCType}\``);
+    if (param === undefined || paramPlan === undefined) {
+        return undefined;
     }
 
-    for (const out of outs) {
-        members.push(outMember(command, out));
+    return { param, paramPlan };
+};
+
+const inParamDocLine = (plan: OkPlan, arg: InArg, docs: GlDocContext): string => {
+    const pair = paramPairFor(plan, arg.name);
+
+    if (pair === undefined) {
+        return ` * @param ${arg.name}`;
     }
 
-    if (members.length === 0) {
-        return undefined;
+    const descriptions = kindDescriptions(pair.param.kinds, docs.kinds);
+    const sentence = descriptions.length === 0 ? "" : `. ${descriptions}`;
+    const notes = metadataNotes(paramShape(pair.param, pair.paramPlan, arg.tsType));
+
+    return ` * @param ${arg.name} - ${notes}${sentence}`;
+};
+
+const outMember = (plan: OkPlan, out: OutArg): string => {
+    const { param, paramPlan } = paramPairAt(plan, out.paramIndex);
+
+    if (param === undefined || paramPlan === undefined) {
+        throw new Error(`Output parameter index ${String(out.paramIndex)} out of range on ${plan.command.name}`);
     }
 
+    return `${backtick(param.name)} (${metadataNotes(paramShape(param, paramPlan, out.tsType))})`;
+};
+
+const returnsDocLine = (plan: OkPlan, outs: OutArg[]): string | undefined => {
+    const members = [
+        ...(plan.returnPlan.kind === "void" ? [] : [metadataNotes(returnShape(plan))]),
+        ...outs.map((out) => outMember(plan, out)),
+    ];
+
     const [single] = members;
 
-    if (single !== undefined && members.length === 1) {
+    if (single === undefined) {
+        return undefined;
+    }
+
+    if (members.length === 1) {
         return ` * @returns ${single}`;
     }
 
     return ` * @returns Tuple of ${members.join(", ")}`;
 };
 
-const singularJsDoc = ({ commandName, feature, summary, body }: SingularJsDocOptions): string =>
+const tagBlock = (tags: string[]): string[] => (tags.length === 0 ? [] : [" *", ...tags]);
+
+const derivedJsDoc = ({ command, provenance, summary, body, docs }: DerivedJsDocOptions): string =>
     [
         "/**",
         ` * ${summary}`,
         " *",
-        ` * Provided by \`${feature}\`.`,
-        ...body,
-        ` * @see ${REFPAGES_BASE}/${commandName}.xhtml`,
+        ...provenanceLines(provenance, docs.extensionCommands.get(command.name) ?? []),
+        ...tagBlock(body),
         " */",
     ].join("\n");
 
-const commandJsDoc = ({ command, feature, ins, outs, returnPlan }: CommandJsDocOptions): string => {
-    const returnsLine = returnsDocLine(command, returnPlan, outs);
-
-    return singularJsDoc({
-        commandName: command.name,
-        feature,
-        summary: `\`${formatPrototype(command)}\``,
-        body: [
-            ...(ins.length > 0 ? [" *", ...ins.map((arg) => inParamDocLine(command, arg))] : []),
-            ...(returnsLine === undefined ? [] : [returnsLine]),
-        ],
-    });
+const commandJsDoc = ({ plan, provenance, ins, outs, docs }: CommandJsDocOptions): string => {
+    const { command } = plan;
+    const returnsLine = returnsDocLine(plan, outs);
+
+    const tags = [
+        ...ins.map((arg) => inParamDocLine(plan, arg, docs)),
+        ...(returnsLine === undefined ? [] : [returnsLine]),
+    ];
+
+    return [
+        "/**",
+        ` * ${backtick(formatPrototype(command))}`,
+        " *",
+        ...provenanceLines(provenance, docs.extensionCommands.get(command.name) ?? []),
+        ...commandNotes(command, docs),
+        ...tagBlock(tags),
+        " */",
+    ].join("\n");
 };
 
-export { inParamDocLine, singularJsDoc, commandJsDoc };
+export { commandJsDoc, derivedJsDoc, inParamDocLine };