From 6984d0e78fb62197cf98d834994980e4072ae793 Mon Sep 17 00:00:00 2001 From: Nick Wylynko Date: Tue, 1 Jul 2025 11:30:05 -0700 Subject: [PATCH 1/3] wip --- .typedoc/custom-theme.mjs | 21 +++++++++++++++++++++ package.json | 1 + 2 files changed, 22 insertions(+) diff --git a/.typedoc/custom-theme.mjs b/.typedoc/custom-theme.mjs index 20b8ab3715d..8a21ace2956 100644 --- a/.typedoc/custom-theme.mjs +++ b/.typedoc/custom-theme.mjs @@ -412,6 +412,27 @@ ${tabs} * Hide "Extends" and "Extended by" sections */ hierarchy: () => '', + /** + * @param {import('typedoc').DeclarationReflection} model + * @param {{ headingLevel: number }} options + */ + accessor: (model, options) => { + // const defaultOutput = superPartials.accessor(model, options); + + const name = model.name; + + const type = model.getSignature?.type?.toString(); + + const comment = model.getSignature?.comment?.summary.reduce((acc, curr) => acc + curr.text, ''); + + console.log({ + name, + type, + comment, + }); + + return '| ' + '`' + name + '`' + ' | ' + type + ' | ' + comment + ' |'; + }, }; } } diff --git a/package.json b/package.json index d0ac1cadb53..b5b5e7dc7b1 100644 --- a/package.json +++ b/package.json @@ -52,6 +52,7 @@ "test:typedoc": "pnpm typedoc:generate && cd ./.typedoc && vitest run", "turbo:clean": "turbo daemon clean", "typedoc:generate": "pnpm build:declarations && typedoc --tsconfig tsconfig.typedoc.json", + "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json", "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false", "version-packages:canary": "./scripts/canary.mjs", "version-packages:snapshot": "./scripts/snapshot.mjs", From e01819cb3249be323a582af28ae12897dd32026f Mon Sep 17 00:00:00 2001 From: Nick Wylynko Date: Wed, 13 Aug 2025 15:29:37 +0800 Subject: [PATCH 2/3] Extract Accessors group and render it separately in a table format. --- .typedoc/custom-theme.mjs | 86 +++++++++++++++++++++++++++++++-------- 1 file changed, 68 insertions(+), 18 deletions(-) diff --git a/.typedoc/custom-theme.mjs b/.typedoc/custom-theme.mjs index 8a21ace2956..6310f6a3d0a 100644 --- a/.typedoc/custom-theme.mjs +++ b/.typedoc/custom-theme.mjs @@ -218,9 +218,69 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext { const customizedModel = model; customizedModel.typeParameters = undefined; - const output = superPartials.memberWithGroups(customizedModel, options); + // Extract the Accessors group (if any) and prevent default rendering for it + const originalGroups = customizedModel.groups; + const accessorsGroup = originalGroups?.find(g => g.title === 'Accessors'); + const groupsWithoutAccessors = originalGroups?.filter(g => g.title !== 'Accessors'); + + customizedModel.groups = groupsWithoutAccessors; + const nonAccessorOutput = superPartials.memberWithGroups(customizedModel, options); + customizedModel.groups = originalGroups; + + /** @type {string[]} */ + const md = [nonAccessorOutput]; + + if (accessorsGroup && accessorsGroup.children && accessorsGroup.children.length > 0) { + md.push('\n\n## Accessors\n'); + // Table header + // This needs to be 'Property' instead of 'Accessor' so that clerk.com renders it correctly + md.push('| Property | Type | Description |'); + md.push('| --- | --- | --- |'); + + for (const child of accessorsGroup.children) { + /** @type {import('typedoc').DeclarationReflection} */ + // @ts-ignore - child is a DeclarationReflection for accessor members + const decl = child; + // Name and anchor id + const name = decl.name; + const id = name.toLowerCase().replace(/[^a-z0-9]/g, ''); + + // Resolve the accessor type from the getter signature + /** @type {any} */ + const getterSig = /** @type {any} */ (decl).getSignature; + /** @type {any} */ + const setterSig = /** @type {any} */ (decl).setSignature; + let typeStr = ''; + if (getterSig?.type) { + typeStr = this.partials.someType(getterSig.type); + } else if (setterSig?.parameters?.[0]?.type) { + typeStr = this.partials.someType(setterSig.parameters[0].type); + } else if (decl.type) { + typeStr = this.partials.someType(decl.type); + } - return output; + // Prefer comment on the getter signature; fallback to declaration comment + const summary = getterSig?.comment?.summary ?? decl.comment?.summary ?? setterSig?.comment?.summary; + const description = Array.isArray(summary) + ? summary.reduce((acc, curr) => acc + (curr.text || ''), '') + : ''; + + md.push(`| \`${escapeChars(name)}\` | ${typeStr} | ${description} |`); + } + } + + return md.join('\n'); + }, + /** + * Suppress default per-accessor member rendering; table is rendered in memberWithGroups instead. + * @param {import('typedoc').DeclarationReflection} model + * @param {{ headingLevel: number, nested?: boolean }} options + */ + member: (model, options) => { + if (model.kind === ReflectionKind.Accessor) { + return ''; + } + return superPartials.member(model, options); }, /** * This hides the "Type parameters" section and the declaration title from the output @@ -414,24 +474,14 @@ ${tabs} hierarchy: () => '', /** * @param {import('typedoc').DeclarationReflection} model - * @param {{ headingLevel: number }} options */ - accessor: (model, options) => { - // const defaultOutput = superPartials.accessor(model, options); - + accessor: model => { + // Fallback single-row rendering if used directly elsewhere const name = model.name; - - const type = model.getSignature?.type?.toString(); - - const comment = model.getSignature?.comment?.summary.reduce((acc, curr) => acc + curr.text, ''); - - console.log({ - name, - type, - comment, - }); - - return '| ' + '`' + name + '`' + ' | ' + type + ' | ' + comment + ' |'; + const typeStr = model.getSignature?.type ? this.partials.someType(model.getSignature.type) : ''; + const summary = model.getSignature?.comment?.summary ?? model.comment?.summary; + const description = Array.isArray(summary) ? summary.reduce((acc, curr) => acc + (curr.text || ''), '') : ''; + return '| ' + '`' + escapeChars(name) + '`' + ' | ' + typeStr + ' | ' + description + ' |'; }, }; } From 95ac6299ddd275583fba3967291db72e6db19d81 Mon Sep 17 00:00:00 2001 From: Nick Wylynko Date: Wed, 13 Aug 2025 20:28:51 +0800 Subject: [PATCH 3/3] Add empty changeset --- .changeset/old-dolls-smell.md | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 .changeset/old-dolls-smell.md diff --git a/.changeset/old-dolls-smell.md b/.changeset/old-dolls-smell.md new file mode 100644 index 00000000000..a845151cc84 --- /dev/null +++ b/.changeset/old-dolls-smell.md @@ -0,0 +1,2 @@ +--- +---