chore(repo): typedoc - Render accessors to markdown in the same fashion as properties #6532
+77
−3
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
🦋 Changeset detectedLatest commit: 95ac629 The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
11 tasks
@clerk/agent-toolkit
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/dev-cli
@clerk/elements
@clerk/clerk-expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/clerk-react
@clerk/react-router
@clerk/remix
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/themes
@clerk/types
@clerk/upgrade
@clerk/vue
commit: |
📝 WalkthroughWalkthroughThe PR updates the custom TypeDoc Markdown theme to render Accessor members in a dedicated "Accessors" section: adds a new accessor partial, suppresses default per-accessor rendering in member, and changes memberWithGroups and signature to build and append an Accessors table with anchors, computed types, and prioritized descriptions. It also splits the TypeDoc generation script in package.json into two steps by adding typedoc:generate:skip-build and making typedoc:generate delegate to it after building declarations. A new empty changeset file (.changeset/old-dolls-smell.md) is added. Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes 📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
package.json (1)
57-57: Guard against wiping docs when Typedoc failsIf typedoc fails to produce .typedoc/temp-docs, the current script will remove .typedoc/docs and then fail on mv, leaving you without docs. Add a guard to only replace docs when the temp folder exists.
Apply this diff:
- "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && rm -rf .typedoc/docs && mv .typedoc/temp-docs .typedoc/docs", + "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && if [ -d .typedoc/temp-docs ]; then rm -rf .typedoc/docs && mv .typedoc/temp-docs .typedoc/docs; else echo 'Error: missing .typedoc/temp-docs (Typedoc may have failed)'; exit 1; fi",Also consider switching test:typedoc to use typedoc:generate:skip-build when declarations are already built in CI/local to speed the loop.
.typedoc/custom-theme.mjs (1)
221-273: Add tests for Accessors table renderingNo tests are shown in this PR for the new Accessors table. Please add tests that assert:
- The “## Accessors” section is emitted when accessor members exist.
- Rows include correct Property, Type (getter-only, setter-only, getter+setter), and Description (preferring getter comment).
- Proper escaping of names and rendering of comment parts (inline code, links).
- Stable anchor generation for property rows.
I can help scaffold a small fixture class (e.g., User) and assertions against the generated Markdown.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.typedoc/custom-theme.mjs(2 hunks)package.json(1 hunks)
🧰 Additional context used
📓 Path-based instructions (2)
**/*.{js,jsx,ts,tsx,json,css,scss,md,yaml,yml}
📄 CodeRabbit Inference Engine (.cursor/rules/development.mdc)
Use Prettier for consistent code formatting
Files:
package.json
**/*
⚙️ CodeRabbit Configuration File
If there are no tests added or modified as part of the PR, please suggest that tests be added to cover the changes.
Files:
package.json
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)
- GitHub Check: Build Packages
- GitHub Check: Formatting | Dedupe | Changeset
- GitHub Check: semgrep/ci
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: Analyze (javascript-typescript)
🔇 Additional comments (2)
package.json (1)
56-57: Decoupling build and docs generation looks goodSplitting Typedoc generation into build and skip-build steps makes the flow more flexible and cache-friendly. No issues spotted with the scripts as written.
.typedoc/custom-theme.mjs (1)
274-284: Suppressing default Accessor rendering is correctReturning an empty string for ReflectionKind.Accessor prevents duplicate rendering now that accessors are handled in memberWithGroups. Looks good.
Comment on lines
+221
to
+273
| // 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(`| <a id="${id}"></a> \`${escapeChars(name)}\` | ${typeStr} | ${description} |`); | ||
| } | ||
| } | ||
|
|
||
| return md.join('\n'); | ||
| }, |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Use getCommentParts for descriptions and add a safe fallback for empty types
Two improvements:
- Description: prefer the theme helper this.helpers.getCommentParts over manually reducing CommentDisplayPart[] so tags/formatting render correctly.
- Type: if neither getter, setter nor decl.type yields a type, use a visible placeholder (e.g., —) to avoid an empty table cell.
Apply this diff:
- 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);
- }
+ 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);
+ }
+ if (!typeStr) {
+ typeStr = '—';
+ }
@@
- // 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 || ''), '')
- : '';
+ // Prefer comment on the getter signature; fallback to declaration, then setter
+ const summaryParts =
+ getterSig?.comment?.summary ?? decl.comment?.summary ?? setterSig?.comment?.summary;
+ const description = summaryParts ? this.helpers.getCommentParts(summaryParts) : '';Optional: to minimize potential ID collisions, consider prefixing the anchor with the parent name (e.g., ${decl.parent?.name}-${name}) before sanitizing.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| // 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(`| <a id="${id}"></a> \`${escapeChars(name)}\` | ${typeStr} | ${description} |`); | |
| } | |
| } | |
| return md.join('\n'); | |
| }, | |
| 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); | |
| } | |
| if (!typeStr) { | |
| typeStr = '—'; | |
| } | |
| // Prefer comment on the getter signature; fallback to declaration, then setter | |
| const summaryParts = | |
| getterSig?.comment?.summary ?? decl.comment?.summary ?? setterSig?.comment?.summary; | |
| const description = summaryParts ? this.helpers.getCommentParts(summaryParts) : ''; | |
| md.push(`| <a id="${id}"></a> \`${escapeChars(name)}\` | ${typeStr} | ${description} |`); | |
| } |
🤖 Prompt for AI Agents
In .typedoc/custom-theme.mjs around lines 221 to 273, the accessor table
currently builds descriptions by manually reducing CommentDisplayPart[] and
leaves the Type cell empty when no type is resolved; change the description
extraction to use this.helpers.getCommentParts (or
this.helpers.getCommentParts(summary) equivalent) so tags/formatting render
correctly, and ensure typeStr defaults to a visible placeholder (e.g., '—') when
getter/setter/decl.type are all absent; also, to reduce anchor collisions,
prefix the id with the parent name when present (e.g.,
`${decl.parent?.name}-${name}`) before sanitizing and lowercasing.
Comment on lines
+475
to
486
| /** | ||
| * @param {import('typedoc').DeclarationReflection} model | ||
| */ | ||
| accessor: model => { | ||
| // Fallback single-row rendering if used directly elsewhere | ||
| const name = model.name; | ||
| 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 + ' |'; | ||
| }, | ||
| }; |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Align fallback accessor partial with main table logic
For consistency, compute type from getter or setter (with fallback placeholder) and use getCommentParts for the description. This keeps standalone accessor rendering consistent with the table.
Apply this diff:
- accessor: model => {
- // Fallback single-row rendering if used directly elsewhere
- const name = model.name;
- 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 + ' |';
- },
+ accessor: model => {
+ // Fallback single-row rendering if used directly elsewhere
+ const name = model.name;
+ let typeStr = '';
+ if (model.getSignature?.type) {
+ typeStr = this.partials.someType(model.getSignature.type);
+ } else if (model.setSignature?.parameters?.[0]?.type) {
+ typeStr = this.partials.someType(model.setSignature.parameters[0].type);
+ } else if (model.type) {
+ typeStr = this.partials.someType(model.type);
+ }
+ if (!typeStr) {
+ typeStr = '—';
+ }
+ const summaryParts =
+ model.getSignature?.comment?.summary ?? model.comment?.summary ?? model.setSignature?.comment?.summary;
+ const description = summaryParts ? this.helpers.getCommentParts(summaryParts) : '';
+ return '| ' + '`' + escapeChars(name) + '`' + ' | ' + typeStr + ' | ' + description + ' |';
+ },📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| /** | |
| * @param {import('typedoc').DeclarationReflection} model | |
| */ | |
| accessor: model => { | |
| // Fallback single-row rendering if used directly elsewhere | |
| const name = model.name; | |
| 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 + ' |'; | |
| }, | |
| }; | |
| accessor: model => { | |
| // Fallback single-row rendering if used directly elsewhere | |
| const name = model.name; | |
| let typeStr = ''; | |
| if (model.getSignature?.type) { | |
| typeStr = this.partials.someType(model.getSignature.type); | |
| } else if (model.setSignature?.parameters?.[0]?.type) { | |
| typeStr = this.partials.someType(model.setSignature.parameters[0].type); | |
| } else if (model.type) { | |
| typeStr = this.partials.someType(model.type); | |
| } | |
| if (!typeStr) { | |
| typeStr = '—'; | |
| } | |
| const summaryParts = | |
| model.getSignature?.comment?.summary ?? model.comment?.summary ?? model.setSignature?.comment?.summary; | |
| const description = summaryParts ? this.helpers.getCommentParts(summaryParts) : ''; | |
| return '| ' + '`' + escapeChars(name) + '`' + ' | ' + typeStr + ' | ' + description + ' |'; | |
| }, |
🤖 Prompt for AI Agents
In .typedoc/custom-theme.mjs around lines 475 to 486, the fallback accessor
partial currently only reads type from getSignature and builds description
manually; update it to compute type from either getSignature or setSignature
(falling back to the same placeholder used by the main table) and replace the
manual summary/description assembly with a call to getCommentParts for the
appropriate signature so the standalone accessor rendering matches the main
table logic.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
the
Userclass has accessors on itLargely speaking for a consumer of Clerk, these work no differently than standard properties, so we should document them the same. This pr renders them out as a properties table:
Getting us a very nice table in clerk.com
Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
Summary by CodeRabbit