chore(*): Improve @default, @deprecated JSDoc (#5630)

Author: LekoArts

.changeset/fast-lands-smash.md

@@ -0,0 +1,14 @@
+---
+'@clerk/react-router': patch
+'@clerk/clerk-js': patch
+'@clerk/backend': patch
+'@clerk/shared': patch
+'@clerk/astro': patch
+'@clerk/clerk-react': patch
+'@clerk/remix': patch
+'@clerk/types': patch
+'@clerk/clerk-expo': patch
+'@clerk/vue': patch
+---
+
+Improve JSDoc comments

.typedoc/custom-plugin.mjs

@@ -29,7 +29,7 @@ const LINK_REPLACEMENTS = [
   ['sign-up-resource', '/docs/references/javascript/sign-up'],
   ['user-resource', '/docs/references/javascript/user'],
   ['session-status-claim', '/docs/references/javascript/types/session-status'],
-  ['user-organization-invitation-resource', '/docs/references/javascript/types/organization-invitation'],
+  ['user-organization-invitation-resource', '/docs/references/javascript/types/user-organization-invitation'],
   ['organization-membership-resource', '/docs/references/javascript/types/organization-membership'],
   ['organization-suggestion-resource', '/docs/references/javascript/types/organization-suggestion'],
   ['organization-resource', '/docs/references/javascript/organization'],
@@ -62,7 +62,7 @@ function getRelativeLinkReplacements() {
   });
 }
 
-function getUnlinkedTypesReplacements() {
+function getCatchAllReplacements() {
   return [
     {
       pattern: /\(setActiveParams\)/g,
@@ -80,6 +80,20 @@ function getUnlinkedTypesReplacements() {
       pattern: /\(CreateOrganizationParams\)/g,
       replace: '([CreateOrganizationParams](#create-organization-params))',
     },
+    {
+      /**
+       * By default, `@deprecated` is output with `**Deprecated**`. We want to add a full stop to it.
+       */
+      pattern: /\*\*Deprecated\*\*/g,
+      replace: '**Deprecated.**',
+    },
+    {
+      /**
+       * By default, `@default` is output with "**Default** `value`". We want to capture the value and place it inside "Defaults to `value`."
+       */
+      pattern: /\*\*Default\*\* `([^`]+)`/g,
+      replace: 'Defaults to `$1`.',
+    },
   ];
 }
 
@@ -97,9 +111,9 @@ export function load(app) {
       }
     }
 
-    const unlinkedTypesReplacements = getUnlinkedTypesReplacements();
+    const catchAllReplacements = getCatchAllReplacements();
 
-    for (const { pattern, replace } of unlinkedTypesReplacements) {
+    for (const { pattern, replace } of catchAllReplacements) {
       if (output.contents) {
         output.contents = output.contents.replace(pattern, replace);
       }

.typedoc/custom-theme.mjs

@@ -63,6 +63,63 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 
         return output;
       },
+      /**
+       * This condenses the output if only a "simple" return type + `@returns` is given.
+       * @param {import('typedoc').SignatureReflection} model
+       * @param {{ headingLevel: number }} options
+       */
+      signatureReturns: (model, options) => {
+        const defaultOutput = superPartials.signatureReturns(model, options);
+        const hasReturnsTag = model.comment?.getTag('@returns');
+
+        /**
+         * @type {any}
+         */
+        const type = model.type;
+        /**
+         * @type {import('typedoc').DeclarationReflection}
+         */
+        const typeDeclaration = type?.declaration;
+
+        /**
+         * Early return for non "simple" cases
+         */
+        if (!typeDeclaration?.signatures) {
+          if (model.type && this.helpers.hasUsefulTypeDetails(model.type)) {
+            return defaultOutput;
+          }
+        }
+        if (!hasReturnsTag) {
+          return defaultOutput;
+        }
+
+        /**
+         * Now the default output would be in this format:
+         *
+         * `Type`
+         *
+         * Contents of `@returns` tag
+         *
+         * It should be condensed to:
+         *
+         * `Type` — Contents of `@returns` tag
+         */
+
+        const o = defaultOutput.split('\n\n');
+
+        /**
+         * At this stage the output can be:
+         * - ['## Returns', '`Type`', 'Contents of `@returns` tag']
+         * - ['## Returns', '`Type`', '']
+         *
+         * We want to condense the first case by combining the second and third item with ` — `
+         */
+        if (o.length === 3 && o[2] !== '') {
+          return `${o[0]}\n\n${o[1]} — ${o[2]}`;
+        }
+
+        return defaultOutput;
+      },
       /**
        * This hides the "Type parameters" section from the output
        * @param {import('typedoc').DeclarationReflection} model

package.json

@@ -132,7 +132,7 @@
     "turbo-ignore": "^2.4.4",
     "typedoc": "0.28.2",
     "typedoc-plugin-markdown": "4.6.2",
-    "typedoc-plugin-replace-text": "4.1.0",
+    "typedoc-plugin-replace-text": "4.2.0",
     "typescript": "catalog:repo",
     "typescript-eslint": "8.28.0",
     "uuid": "8.3.2",

packages/astro/src/types.ts

@@ -73,8 +73,8 @@ export type { AstroClerkUpdateOptions, AstroClerkIntegrationParams, AstroClerkCr
 
 export type ButtonProps<Tag> = {
   /**
-   * @deprecated The 'as' prop is deprecated and will be removed in a future version.
-   * Use the default slot with the 'asChild' prop instead.
+   * @deprecated The `'as'` prop will be removed in a future version.
+   * Use the default slot with the `'asChild'` prop instead.
    * @example
    * <SignInButton asChild>
    *   <button>Sign in</button>

packages/backend/src/api/endpoints/UserApi.ts

@@ -234,7 +234,7 @@ export class UserAPI extends AbstractAPI {
     });
   }
 
-  /** @deprecated Please use getUserOauthAccessToken without the `oauth_` provider prefix . */
+  /** @deprecated Use `getUserOauthAccessToken` without the `oauth_` provider prefix . */
   public async getUserOauthAccessToken(
     userId: string,
     provider: `oauth_${OAuthProvider}`,

packages/backend/src/api/request.ts

@@ -54,7 +54,7 @@ type BuildRequestOptions = {
   userAgent?: string;
   /**
    * Allow requests without specifying a secret key. In most cases this should be set to `false`.
-   * Defaults to `true`.
+   * @default true
    */
   requireSecretKey?: boolean;
 };

packages/backend/src/jwt/verifyJwt.ts

@@ -108,7 +108,8 @@ export type VerifyJwtOptions = {
    */
   authorizedParties?: string[];
   /**
-   * Specifies the allowed time difference (in milliseconds) between the Clerk server (which generates the token) and the clock of the user's application server when validating a token. Defaults to 5000 ms (5 seconds).
+   * Specifies the allowed time difference (in milliseconds) between the Clerk server (which generates the token) and the clock of the user's application server when validating a token.
+   * @default 5000
    */
   clockSkewInMs?: number;
   /**

packages/backend/src/tokens/keys.ts

@@ -90,7 +90,7 @@ export type LoadClerkJWKFromRemoteOptions = {
    */
   kid: string;
   /**
-   * @deprecated This cache TTL is deprecated and will be removed in the next major version. Specifying a cache TTL is now a no-op.
+   * @deprecated This cache TTL will be removed in the next major version. Specifying a cache TTL is a no-op.
    */
   jwksCacheTtlInMs?: number;
   /**
@@ -102,11 +102,13 @@ export type LoadClerkJWKFromRemoteOptions = {
    */
   secretKey?: string;
   /**
-   * The [Clerk Backend API](https://clerk.com/docs/reference/backend-api) endpoint. Defaults to `'https://api.clerk.com'`.
+   * The [Clerk Backend API](https://clerk.com/docs/reference/backend-api) endpoint.
+   * @default 'https://api.clerk.com'
    */
   apiUrl?: string;
   /**
-   * The version passed to the Clerk API. Defaults to `'v1'`.
+   * The version passed to the Clerk API.
+   * @default 'v1'
    */
   apiVersion?: string;
 };

packages/backend/src/tokens/types.ts

@@ -11,7 +11,8 @@ export type AuthenticateRequestOptions = {
    */
   domain?: string;
   /**
-   * Whether the instance is a satellite domain in a multi-domain setup. Defaults to `false`.
+   * Whether the instance is a satellite domain in a multi-domain setup.
+   * @default false
    */
   isSatellite?: boolean;
   /**
@@ -27,11 +28,13 @@ export type AuthenticateRequestOptions = {
    */
   signUpUrl?: string;
   /**
-   * Full URL or path to navigate to after successful sign in. Defaults to `/`.
+   * Full URL or path to navigate to after successful sign in.
+   * @default '/'
    */
   afterSignInUrl?: string;
   /**
-   * Full URL or path to navigate to after successful sign up. Defaults to `/`.
+   * Full URL or path to navigate to after successful sign up.
+   * @default '/'
    */
   afterSignUpUrl?: string;
   /**