chore(repo): Fix typedoc paramextension tag #6990
Conversation
🦋 Changeset detectedLatest commit: bdc2522 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 GitHub.
|
WalkthroughUpdates the Typedoc custom theme to change where paramExtension is inserted: it now anchors at the "## Parameters" heading, finds the next heading, and inserts before that (or appends if none). Also adds a new changeset file that contains only YAML front-matter delimiters. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Dev as Dev
participant TD as TypeDoc
participant Theme as custom-theme.mjs
participant Page as Markdown
Dev->>TD: Run docs build
TD->>Theme: Provide rendered page items
Theme->>Page: Search for "## Parameters"
alt "## Parameters" found
Theme->>Page: Scan forward for next "##" heading
alt Next heading exists
Theme->>Page: Insert paramExtension before next heading
else No subsequent heading
Theme->>Page: Append paramExtension at end
end
else "## Parameters" not found
Theme->>Page: Do not insert paramExtension
end
Page-->>TD: Emit updated markdown
TD-->>Dev: Generated docs
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
Pre-merge checks and finishing touches✅ Passed checks (5 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Disabled knowledge base sources:
📒 Files selected for processing (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). (5)
🔇 Additional comments (1)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
.typedoc/custom-theme.mjs (2)
79-79: Remove the empty comment.This empty comment serves no purpose and should be removed to keep the code clean.
Apply this diff:
- // if (paramExtensionTag) {
83-84: Consider more precise heading matching.The current
includes('## Parameters')check could theoretically match false positives like "## Parameters and More". While unlikely in typical TypeDoc output, a more precise check would improve robustness.Apply this diff:
// Find the index of the item that contains '## Parameters' - const parametersIndex = splitOutput.findIndex(item => item.includes('## Parameters')); + const parametersIndex = splitOutput.findIndex(item => item.trim().startsWith('## Parameters'));
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
.changeset/five-schools-repair.md(1 hunks).typedoc/custom-theme.mjs(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
.changeset/**
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Automated releases must use Changesets.
Files:
.changeset/five-schools-repair.md
🪛 LanguageTool
.changeset/five-schools-repair.md
[grammar] ~1-~1: Hier könnte ein Fehler sein.
Context: --- ---
(QB_NEW_DE)
⏰ 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: Analyze (javascript-typescript)
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: semgrep-cloud-platform/scan
🔇 Additional comments (2)
.typedoc/custom-theme.mjs (2)
86-98: LGTM! The next-heading search logic is correct.The implementation properly:
- Guards against invalid parametersIndex
- Searches forward from the Parameters section
- Uses appropriate regex to match markdown headings
- Handles the case where no subsequent heading exists
100-103: LGTM! Insertion logic correctly fixes the reported issue.The implementation now properly injects paramExtension content:
- Before the next heading (if one exists after Parameters)
- At the end of the page (if no subsequent heading exists)
This addresses the issue reported in DOCS-11069 where content was not appearing when the "## Returns" heading was missing.
| --- | ||
| --- |
There was a problem hiding this comment.
Complete the changeset file for automated releases.
This changeset file is incomplete. According to the project's coding guidelines, automated releases require proper Changesets format. A valid changeset should include:
- Package names and version bump types between the YAML delimiters:
---
"@clerk/backend": patch
---- A description of the changes below the front matter:
---
"@clerk/backend": patch
---
Fix typedoc paramExtension tag injection to work without "## Returns" heading🧰 Tools
🪛 LanguageTool
[grammar] ~1-~1: Hier könnte ein Fehler sein.
Context: --- ---
(QB_NEW_DE)
🤖 Prompt for AI Agents
In .changeset/five-schools-repair.md around lines 1 to 2, the changeset is
empty; add a proper Changesets front matter containing the package name(s) and
the version bump type (patch/minor/major) between the YAML delimiters and then
add a short description of the change below the front matter so automated
releases can parse it (e.g., include "@clerk/backend": patch in the YAML and a
one-line description of the fix beneath).
@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: |
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (1)
.typedoc/custom-theme.mjs (1)
82-103: LGTM! Logic correctly addresses the injection issue.The new implementation properly handles cases where the "## Returns" heading is absent by scanning for any heading after "## Parameters" and inserting content before it (or at the end if no heading exists). The bounds checking and index calculations are correct.
Minor: Consider renaming
stufffor clarity.The variable name
stuff(line 80) could be more descriptive:- const stuff = this.helpers.getCommentParts(paramExtensionTag.content); + const paramExtensionContent = this.helpers.getCommentParts(paramExtensionTag.content); // Find the index of the item that contains '## Parameters' const parametersIndex = splitOutput.findIndex(item => item.includes('## Parameters')); @@ ... @@ // (or at the end of the entire page if no heading found) const insertIndex = nextHeadingIndex !== -1 ? nextHeadingIndex : splitOutput.length; - splitOutput.splice(insertIndex, 0, stuff); + splitOutput.splice(insertIndex, 0, paramExtensionContent); }
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
.typedoc/custom-theme.mjs(1 hunks)
⏰ 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). (24)
- GitHub Check: Integration Tests (nextjs, chrome, 15)
- GitHub Check: Integration Tests (billing, chrome)
- GitHub Check: Integration Tests (nextjs, chrome, 14)
- GitHub Check: Integration Tests (react-router, chrome)
- GitHub Check: Integration Tests (handshake:staging, chrome)
- GitHub Check: Integration Tests (nuxt, chrome)
- GitHub Check: Integration Tests (astro, chrome)
- GitHub Check: Integration Tests (custom, chrome)
- GitHub Check: Integration Tests (vue, chrome)
- GitHub Check: Integration Tests (tanstack-react-start, chrome)
- GitHub Check: Integration Tests (handshake, chrome)
- GitHub Check: Integration Tests (machine, chrome)
- GitHub Check: Integration Tests (ap-flows, chrome)
- GitHub Check: Integration Tests (sessions, chrome)
- GitHub Check: Integration Tests (expo-web, chrome)
- GitHub Check: Integration Tests (express, chrome)
- GitHub Check: Integration Tests (localhost, chrome)
- GitHub Check: Integration Tests (sessions:staging, chrome)
- GitHub Check: Integration Tests (quickstart, chrome)
- GitHub Check: Integration Tests (elements, chrome)
- GitHub Check: Integration Tests (generic, chrome)
- GitHub Check: Publish with pkg-pr-new
- GitHub Check: semgrep-cloud-platform/scan
- GitHub Check: semgrep-cloud-platform/scan
.typedoc/custom-theme.mjs
Outdated
| let nextHeadingIndex = -1; | ||
| for (let i = parametersIndex + 1; i < splitOutput.length; i++) { | ||
| const item = splitOutput[i].trim(); | ||
|
|
||
| // The next header has to, at a minimum, start with ## | ||
| // because it comes after '## Parameters' | ||
| if (item.match(/^##/)) { | ||
| nextHeadingIndex = i; | ||
| break; | ||
| } | ||
| } |
There was a problem hiding this comment.
| let nextHeadingIndex = -1; | |
| for (let i = parametersIndex + 1; i < splitOutput.length; i++) { | |
| const item = splitOutput[i].trim(); | |
| // The next header has to, at a minimum, start with ## | |
| // because it comes after '## Parameters' | |
| if (item.match(/^##/)) { | |
| nextHeadingIndex = i; | |
| break; | |
| } | |
| } | |
| const nextHeadingIndex = splitOutput.findIndex((item, index) => { | |
| // skip the items before the parameters | |
| if (index <= parametersIndex) return false; | |
| // find the next heading | |
| return item.startsWith('##') || item.startsWith('\n##') | |
| }) |
Can we just use another findIndex()?
2 participants
Description
The
@paramExtensionstag was relying on a "## Returns" section to inject the paramExtensions content before that "## Returns" section. But sometimes, a page will not have a "## Returns" section, and therefore, the logic wasn't injecting the paramExtensions content anywhere.This PR updates the logic to look for any heading following "## Parameters" and inject the paramExtensions content before it. If it can't find one, it injects the content at the bottom of the page (so at the very least, the content is at least on the page).
FIXES DOCS-11069
Checklist
pnpm testruns as expected.pnpm buildruns as expected.Type of change
Summary by CodeRabbit