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

Author: alexisintech

.changeset/silly-jars-shave.md

@@ -0,0 +1,2 @@
+---
+---

.typedoc/custom-theme.mjs

@@ -44,6 +44,8 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 
     const superPartials = this.partials;
 
+    this._insideFunctionSignature = false;
+
     this.partials = {
       ...superPartials,
       /**
@@ -153,10 +155,17 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
           );
         }
 
+        const prevInsideParams = this._insideFunctionSignature;
+        this._insideFunctionSignature = true;
         md.push(this.partials.signatureParameters(model.parameters || []));
+        this._insideFunctionSignature = prevInsideParams;
 
         if (model.type) {
-          md.push(`: ${this.partials.someType(model.type)}`);
+          const prevInsideType = this._insideFunctionSignature;
+          this._insideFunctionSignature = true;
+          const typeOutput = this.partials.someType(model.type);
+          this._insideFunctionSignature = prevInsideType;
+          md.push(`: ${typeOutput}`);
         }
 
         const result = md.join('');
@@ -353,6 +362,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>`;
       },
       /**
@@ -371,6 +385,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>`;
       },
       /**
@@ -394,6 +413,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>`;
       },
       /**
@@ -492,6 +516,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>`;
       },
       /**

packages/backend/src/tokens/verify.ts

@@ -40,22 +40,11 @@ export type VerifyTokenOptions = Simplify<
  * Verifies a Clerk-generated token signature. Networkless if the `jwtKey` is provided. Otherwise, performs a network call to retrieve the JWKS from the [Backend API](https://clerk.com/docs/reference/backend-api/tag/JWKS#operation/GetJWKS){{ target: '_blank' }}.
  *
  * @param token - The token to verify.
- * @param options - Options for verifying the token.
+ * @param options - Options for verifying the token. 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: `verifyToken(token, { secretKey: process.env.CLERK_SECRET_KEY })`.
  *
  * @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.