Skip to content

chore(repo): Typedoc: Handle <code> injection in function signatures #7010

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

chore(repo): Typedoc: Handle <code> injection in function signatures #7010

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 47 additions & 1 deletion .typedoc/custom-theme.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,10 +143,15 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
);
}

this._insideFunctionSignature = true;
md.push(this.partials.signatureParameters(model.parameters || []));
this._insideFunctionSignature = false;

if (model.type) {
md.push(`: ${this.partials.someType(model.type)}`);
this._insideFunctionSignature = true;
const typeOutput = this.partials.someType(model.type);
this._insideFunctionSignature = false;
md.push(`: ${typeOutput}`);
}
Comment on lines +146 to 155
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Restore _insideFunctionSignature after nested calls

When superPartials.signatureParameters/someType recurse into other signature renderers (e.g., function types inside parameter or return types), our overridden signatureTitle runs again and unconditionally clears _insideFunctionSignature. Without restoring the previous state, the outer signature loses the guard and nested fragments fall back to <code>-wrapping—the bug we’re trying to prevent resurfaces for composed signatures (think callbacks or higher-order function returns). Capture the prior value and restore it after the call.

-        this._insideFunctionSignature = true;
-        md.push(this.partials.signatureParameters(model.parameters || []));
-        this._insideFunctionSignature = false;
+        const prevInsideParams = this._insideFunctionSignature;
+        this._insideFunctionSignature = true;
+        md.push(this.partials.signatureParameters(model.parameters || []));
+        this._insideFunctionSignature = prevInsideParams;
 
         if (model.type) {
-          this._insideFunctionSignature = true;
-          const typeOutput = this.partials.someType(model.type);
-          this._insideFunctionSignature = false;
+          const prevInsideType = this._insideFunctionSignature;
+          this._insideFunctionSignature = true;
+          const typeOutput = this.partials.someType(model.type);
+          this._insideFunctionSignature = prevInsideType;
           md.push(`: ${typeOutput}`);
         }
📝 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
this._insideFunctionSignature = true;
md.push(this.partials.signatureParameters(model.parameters || []));
this._insideFunctionSignature = false;
if (model.type) {
md.push(`: ${this.partials.someType(model.type)}`);
this._insideFunctionSignature = true;
const typeOutput = this.partials.someType(model.type);
this._insideFunctionSignature = false;
md.push(`: ${typeOutput}`);
}
const prevInsideParams = this._insideFunctionSignature;
this._insideFunctionSignature = true;
md.push(this.partials.signatureParameters(model.parameters || []));
this._insideFunctionSignature = prevInsideParams;
if (model.type) {
const prevInsideType = this._insideFunctionSignature;
this._insideFunctionSignature = true;
const typeOutput = this.partials.someType(model.type);
this._insideFunctionSignature = prevInsideType;
md.push(`: ${typeOutput}`);
}
🤖 Prompt for AI Agents 
In .typedoc/custom-theme.mjs around lines 146 to 155, the code unconditionally
sets this._insideFunctionSignature = true before calling signatureParameters and
someType but does not restore the previous value, which breaks nesting when
those calls re-enter signature rendering; save the current value (e.g., const
prev = this._insideFunctionSignature), set it to true for the nested call, then
after the call restore this._insideFunctionSignature = prev — apply this pattern
to both the signatureParameters and someType calls so the original flag is
always restored even when nested renders occur.


const result = md.join('');
Expand Down Expand Up @@ -343,6 +348,11 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
.replace(/<code>/g, '')
.replace(/<\/code>/g, '');

// Only wrap in <code> if NOT inside a function signature
if (this._insideFunctionSignature) {
return output;
}

return `<code>${output}</code>`;
},
/**
Expand All @@ -361,6 +371,11 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
.replace(/<code>/g, '')
.replace(/<\/code>/g, '');

// Only wrap in <code> if NOT inside a function signature
if (this._insideFunctionSignature) {
return output;
}

return `<code>${output}</code>`;
},
/**
Expand All @@ -384,6 +399,11 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
)
.join(delimiter);

// Only wrap in <code> if NOT inside a function signature
if (this._insideFunctionSignature) {
return output;
}

return `<code>${output}</code>`;
},
/**
Expand Down Expand Up @@ -482,6 +502,32 @@ ${tabs}
.replace(/<code>/g, '')
.replace(/<\/code>/g, '');

// Only wrap in <code> if NOT inside a function signature
if (this._insideFunctionSignature) {
return output;
}

return `<code>${output}</code>`;
},
/**
* Ensures that reflection types (like Simplify wrapped types) are wrapped in a single codeblock
* @param {import('typedoc').ReflectionType} model
*/
reflectionType: model => {
const defaultOutput = superPartials.reflectionType(model);

const output = defaultOutput
// Remove any backticks
.replace(/`/g, '')
// Remove any `<code>` and `</code>` tags
.replace(/<code>/g, '')
.replace(/<\/code>/g, '');

// Only wrap in <code> if NOT inside a function signature
if (this._insideFunctionSignature) {
return output;
}

return `<code>${output}</code>`;
},
/**
Expand Down
11 changes: 0 additions & 11 deletions packages/backend/src/tokens/verify.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,17 +45,6 @@ export type VerifyTokenOptions = Simplify<
* @displayFunctionSignature
* @hideReturns
*
* @paramExtension
*
* ### `VerifyTokenOptions`
*
* It is recommended to set these options as [environment variables](/docs/guides/development/clerk-environment-variables#api-and-sdk-configuration) where possible, and then pass them to the function. For example, you can set the `secretKey` option using the `CLERK_SECRET_KEY` environment variable, and then pass it to the function like this: `createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY })`.
*
* > [!WARNING]
* You must provide either `jwtKey` or `secretKey`.
*
* <Typedoc src="backend/verify-token-options" />
*
* @example
*
* The following example demonstrates how to use the [JavaScript Backend SDK](https://clerk.com/docs/reference/backend/overview) to verify the token signature.
Expand Down