chore(repo): Add @unionReturnHeadings Typedoc blockTag

.changeset/whole-wasps-know.md

@@ -0,0 +1,10 @@
+---
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+'@clerk/shared': patch
+'@clerk/clerk-react': patch
+'@clerk/types': patch
+'@clerk/vue': patch
+---
+
+Improve JSDoc comments

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -27,10 +27,16 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/localization-resource.mdx",
   "types/multi-domain-and-or-proxy.mdx",
   "types/organization-custom-role-key.mdx",
+  "types/organization-domain-resource.mdx",
   "types/organization-domain-verification-status.mdx",
   "types/organization-enrollment-mode.mdx",
+  "types/organization-invitation-resource.mdx",
   "types/organization-invitation-status.mdx",
+  "types/organization-membership-request-resource.mdx",
+  "types/organization-membership-resource.mdx",
   "types/organization-permission-key.mdx",
+  "types/organization-resource.mdx",
+  "types/organization-suggestion-resource.mdx",
   "types/organization-suggestion-status.mdx",
   "types/organizations-jwt-claim.mdx",
   "types/override.mdx",
@@ -57,6 +63,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/use-sign-in-return.mdx",
   "types/use-sign-up-return.mdx",
   "types/use-user-return.mdx",
+  "types/user-organization-invitation-resource.mdx",
   "types/user-resource.mdx",
   "types/without.mdx",
   "shared/build-clerk-js-script-attributes.mdx",

.typedoc/custom-plugin.mjs

@@ -14,6 +14,7 @@ const FILES_WITHOUT_HEADINGS = [
   'paginated-hook-config.mdx',
   'use-organization-list-return.mdx',
   'use-organization-list-params.mdx',
+  'create-organization-params.mdx',
 ];
 
 /**
@@ -28,6 +29,13 @@ 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'],
+  ['organization-membership-resource', '/docs/references/javascript/types/organization-membership'],
+  ['organization-suggestion-resource', '/docs/references/javascript/types/organization-suggestion'],
+  ['organization-resource', '/docs/references/javascript/organization'],
+  ['organization-domain-resource', '/docs/references/javascript/types/organization-domain'],
+  ['organization-invitation-resource', '/docs/references/javascript/types/organization-invitation'],
+  ['organization-membership-request-resource', '/docs/references/javascript/types/organization-membership-request'],
 ];
 
 /**
@@ -69,8 +77,8 @@ function getUnlinkedTypesReplacements() {
       replace: '[Clerk](/docs/references/javascript/clerk)',
     },
     {
-      pattern: /`OrganizationCustomRoleKey`/g,
-      replace: '[OrganizationCustomRoleKey](/docs/references/javascript/types/organization-custom-role-key)',
+      pattern: /\(CreateOrganizationParams\)/g,
+      replace: '([CreateOrganizationParams](#create-organization-params))',
     },
   ];
 }

.typedoc/custom-theme.mjs

@@ -18,6 +18,17 @@ class ClerkMarkdownTheme extends MarkdownTheme {
   }
 }
 
+/**
+ * This map stores the comment for the first item in a union type.
+ * It'll be used to add that comment to the other items of the union type.
+ * This way the comment only has to be added once.
+ * @type {Map<string, import('typedoc').Comment>}
+ *
+ * The key is a concenation of the model's type name and the union type's declaration name.
+ * The value is the comment
+ */
+const unionCommentMap = new Map();
+
 /**
  * Our custom Clerk theme
  * @extends MarkdownThemeContext
@@ -88,6 +99,30 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
 
         return output;
       },
+      /**
+       * This ensures that everything is wrapped in a single codeblock
+       * @param {import('typedoc').DeclarationReflection} model
+       * @param {{ forceCollapse?: boolean }} [options]
+       */
+      declarationType: (model, options) => {
+        const defaultOutput = superPartials.declarationType(model, options);
+
+        // Ensure that the output starts with `\{ `. Some strings will do, some will have e.g. `\{<code>` or `\{[]`
+        const withCorrectWhitespaceAtStart = defaultOutput.startsWith('\\{ ')
+          ? defaultOutput
+          : defaultOutput.startsWith('\\{')
+            ? defaultOutput.replace('\\{', '\\{ ')
+            : defaultOutput;
+
+        const output = withCorrectWhitespaceAtStart
+          // Remove any backticks
+          .replace(/`/g, '')
+          // Remove any `<code>` and `</code>` tags
+          .replace(/<code>/g, '')
+          .replace(/<\/code>/g, '');
+
+        return `<code>${output}</code>`;
+      },
       /**
        * This modifies the output of union types by wrapping everything in a single `<code>foo | bar</code>` tag instead of doing `<code>foo</code>` | `<code>bar</code>`
        * @param {import('typedoc').UnionType} model
@@ -107,7 +142,7 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
         return `<code>${output}</code>`;
       },
       /**
-       * This ensures that everything is wrapped in a single codeblock (not individual ones)
+       * This ensures that everything is wrapped in a single codeblock
        * @param {import('typedoc').SignatureReflection[]} model
        * @param {{ forceParameterType?: boolean; typeSeparator?: string }} [options]
        */
@@ -132,7 +167,7 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
       /**
        * Copied from original theme.
        * Changes:
-       * - Remove summaries over tables (TODO: Use elementSummaries instead)
+       * - Remove summaries over tables and instead use `@unionReturnHeadings` to add headings
        * - Only use one newline between items
        * https://github.com/typedoc2md/typedoc-plugin-markdown/blob/7032ebd3679aead224cf23bffd0f3fb98443d16e/packages/typedoc-plugin-markdown/src/theme/context/partials/member.typeDeclarationUnionContainer.ts
        * @param {import('typedoc').DeclarationReflection} model
@@ -143,10 +178,51 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
          * @type {string[]}
          */
         const md = [];
+        /**
+         * @type {string[]}
+         */
+        const headings = [];
+        /**
+         * Search for the `@unionReturnHeadings` tag in the comment of the model
+         */
+        const unionReturnHeadings = model.comment?.getTag('@unionReturnHeadings');
+
         if (model.type instanceof UnionType) {
           const elementSummaries = model.type?.elementSummaries;
           model.type.types.forEach((type, i) => {
             if (type instanceof ReflectionType) {
+              if (unionReturnHeadings && unionReturnHeadings.content.length > 0) {
+                const content = this.helpers.getCommentParts(unionReturnHeadings.content);
+                const unionHeadings = JSON.parse(content);
+
+                /**
+                 * While iterating over the union types, the headings are pulled from `@unionReturnHeadings` and added to the array
+                 */
+                headings.push(unionHeadings[i]);
+
+                /**
+                 * The `model.type.types` is the array of the individual items of the union type.
+                 * We're documenting our code by only adding the comment to the first item of the union type.
+                 *
+                 * In this block, we're doing the following:
+                 * 1. Generate an ID for the item in the unionCommentMap
+                 * 2. Check if the union type has a comment (truthy for the first item)
+                 * 3. Add the comment to the map
+                 * 4. If the union doesn't have a comment for the given ID, add the comment from the map to the item
+                 */
+                if (type.declaration.children) {
+                  for (const decl of type.declaration.children) {
+                    const id = `${model.name}-${decl.name}`;
+
+                    if (decl.comment && !unionCommentMap.has(id)) {
+                      unionCommentMap.set(id, decl.comment);
+                    } else if (!decl.comment && unionCommentMap.has(id)) {
+                      decl.comment = unionCommentMap.get(id);
+                    }
+                  }
+                }
+              }
+
               md.push(this.partials.typeDeclarationContainer(model, type.declaration, options));
             } else {
               md.push(`${this.partials.someType(type)}`);
@@ -156,7 +232,33 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext {
             }
           });
         }
-        return md.join('\n');
+
+        if (!unionReturnHeadings) {
+          return md.join('\n');
+        }
+
+        const items = headings.map(i => `'${i}'`).join(', ');
+        const tabs = md.map(i => `<Tab>${i}</Tab>`).join('\n');
+
+        return `<Tabs items={[${items}]}>
+${tabs}
+</Tabs>`;
+      },
+      /**
+       * This ensures that everything is wrapped in a single codeblock
+       * @param {import('typedoc').ArrayType} model
+       */
+      arrayType: model => {
+        const defaultOutput = superPartials.arrayType(model);
+
+        const output = defaultOutput
+          // Remove any backticks
+          .replace(/`/g, '')
+          // Remove any `<code>` and `</code>` tags
+          .replace(/<code>/g, '')
+          .replace(/<\/code>/g, '');
+
+        return `<code>${output}</code>`;
       },
     };
   }

packages/backend/src/tokens/types.ts

@@ -35,7 +35,7 @@ export type AuthenticateRequestOptions = {
    */
   afterSignUpUrl?: string;
   /**
-   * Used to activate a specific [organization](https://clerk.com/docs/organizations/overview) or [personal account](https://clerk.com/docs/organizations/organization-workspaces#organization-workspaces-in-the-clerk-dashboard:~:text=Personal%20account) based on URL path parameters. If there's a mismatch between the active organization in the session (e.g., as reported by `auth()`) and the organization indicated by the URL, an attempt to activate the organization specified in the URL will be made.
+   * Used to activate a specific [organization](https://clerk.com/docs/organizations/overview) or [personal account](https://clerk.com/docs/organizations/organization-workspaces) based on URL path parameters. If there's a mismatch between the active organization in the session (e.g., as reported by `auth()`) and the organization indicated by the URL, an attempt to activate the organization specified in the URL will be made.
    *
    * If the activation can't be performed, either because an organization doesn't exist or the user lacks access, the active organization in the session won't be changed. Ultimately, it's the responsibility of the page to verify that the resources are appropriate to render given the URL and handle mismatches appropriately (e.g., by returning a 404).
    */

packages/backend/src/tokens/verify.ts

@@ -10,7 +10,7 @@ import { loadClerkJWKFromLocal, loadClerkJWKFromRemote } from './keys';
 export type VerifyTokenOptions = Omit<VerifyJwtOptions, 'key'> &
   Omit<LoadClerkJWKFromRemoteOptions, 'kid'> & {
     /**
-     * Used to verify the session token in a networkless manner. Supply the PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. **It's recommended to use [the environment variable](https://clerk.com/docs/deployments/clerk-environment-variables) instead.** For more information, refer to [Manual JWT verification](https://clerk.com/docs/backend-requests/handling/manual-jwt).
+     * Used to verify the session token in a networkless manner. Supply the PEM public key from the **[**API keys**](https://dashboard.clerk.com/last-active?path=api-keys) page -> Show JWT public key -> PEM Public Key** section in the Clerk Dashboard. **It's recommended to use [the environment variable](https://clerk.com/docs/deployments/clerk-environment-variables) instead.** For more information, refer to [Manual JWT verification](https://clerk.com/docs/backend-requests/manual-jwt).
      */
     jwtKey?: string;
   };

packages/nextjs/src/app-router/server/currentUser.ts

@@ -9,7 +9,7 @@ import { auth } from './auth';
  * Under the hood, this helper:
  * - calls `fetch()`, so it is automatically deduped per request.
  * - uses the [`GET /v1/users/{user_id}`](https://clerk.com/docs/reference/backend-api/tag/Users#operation/GetUser) endpoint.
- * - counts towards the [Backend API request rate limit](https://clerk.com/docs/backend-requests/resources/rate-limits#rate-limits).
+ * - counts towards the [Backend API request rate limit](https://clerk.com/docs/backend-requests/resources/rate-limits).
  *
  * @example
  * ```tsx {{ filename: 'app/page.tsx' }}

packages/react/src/components/controlComponents.tsx

@@ -170,7 +170,7 @@ export const RedirectToSignUp = withClerk(({ clerk, ...props }: WithClerkProp<Re
 
 /**
  * @function
- * @deprecated Use [`redirectToUserProfile()`](https://clerk.com/docs/references/javascript/clerk/redirect-methods#redirect-to-user-profile) instead, will be removed in the next major version.
+ * @deprecated Use [`redirectToUserProfile()`](https://clerk.com/docs/references/javascript/clerk#redirect-to-user-profile) instead, will be removed in the next major version.
  */
 export const RedirectToUserProfile = withClerk(({ clerk }) => {
   React.useEffect(() => {
@@ -183,7 +183,7 @@ export const RedirectToUserProfile = withClerk(({ clerk }) => {
 
 /**
  * @function
- * @deprecated Use [`redirectToOrganizationProfile()`](https://clerk.com/docs/references/javascript/clerk/redirect-methods#redirect-to-organization-profile) instead, will be removed in the next major version.
+ * @deprecated Use [`redirectToOrganizationProfile()`](https://clerk.com/docs/references/javascript/clerk#redirect-to-organization-profile) instead, will be removed in the next major version.
  */
 export const RedirectToOrganizationProfile = withClerk(({ clerk }) => {
   React.useEffect(() => {
@@ -196,7 +196,7 @@ export const RedirectToOrganizationProfile = withClerk(({ clerk }) => {
 
 /**
  * @function
- * @deprecated Use [`redirectToCreateOrganization()`](https://clerk.com/docs/references/javascript/clerk/redirect-methods#redirect-to-create-organization) instead, will be removed in the next major version.
+ * @deprecated Use [`redirectToCreateOrganization()`](https://clerk.com/docs/references/javascript/clerk#redirect-to-create-organization) instead, will be removed in the next major version.
  */
 export const RedirectToCreateOrganization = withClerk(({ clerk }) => {
   React.useEffect(() => {

packages/react/src/hooks/useAuth.ts

@@ -30,6 +30,9 @@ type UseAuthOptions = Nullish<InitialAuthState | PendingSessionOptions>;
  * By default, Next.js opts all routes into static rendering. If you need to opt a route or routes into dynamic rendering because you need to access the authentication data at request time, you can create a boundary by passing the `dynamic` prop to `<ClerkProvider>`. See the [guide on rendering modes](https://clerk.com/docs/references/nextjs/rendering-modes) for more information, including code examples.
  * </If>
  *
+ * @unionReturnHeadings
+ * ["Initialization", "Signed out", "Signed in (no active organization)", "Signed in (with active organization)"]
+ *
  * @param [initialAuthStateOrOptions] - An object containing the initial authentication state. If not provided, the hook will attempt to derive the state from the context.
  *
  * @function

packages/react/src/hooks/useSignIn.ts

@@ -6,12 +6,15 @@ import { useIsomorphicClerkContext } from '../contexts/IsomorphicClerkContext';
 import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvider';
 
 /**
- * The `useSignIn()` hook provides access to the [`SignIn`](https://clerk.com/docs/references/javascript/sign-in/sign-in) object, which allows you to check the current state of a sign-in attempt and manage the sign-in flow. You can use this to create a [custom sign-in flow](https://clerk.com/docs/custom-flows/overview#sign-in-flow).
+ * The `useSignIn()` hook provides access to the [`SignIn`](https://clerk.com/docs/references/javascript/sign-in) object, which allows you to check the current state of a sign-in attempt and manage the sign-in flow. You can use this to create a [custom sign-in flow](https://clerk.com/docs/custom-flows/overview#sign-in-flow).
+ *
+ * @unionReturnHeadings
+ * ["Initialization", "Loaded"]
  *
  * @example
  * ### Check the current state of a sign-in
  *
- * The following example uses the `useSignIn()` hook to access the [`SignIn`](https://clerk.com/docs/references/javascript/sign-in/sign-in) object, which contains the current sign-in attempt status and methods to create a new sign-in attempt. The `isLoaded` property is used to handle the loading state.
+ * The following example uses the `useSignIn()` hook to access the [`SignIn`](https://clerk.com/docs/references/javascript/sign-in) object, which contains the current sign-in attempt status and methods to create a new sign-in attempt. The `isLoaded` property is used to handle the loading state.
  *
  * <Tabs items='React,Next.js'>
  * <Tab>

packages/react/src/hooks/useSignUp.ts

@@ -6,12 +6,15 @@ import { useIsomorphicClerkContext } from '../contexts/IsomorphicClerkContext';
 import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvider';
 
 /**
- * The `useSignUp()` hook provides access to the [`SignUp`](https://clerk.com/docs/references/javascript/sign-up/sign-up) object, which allows you to check the current state of a sign-up attempt and manage the sign-up flow. You can use this to create a [custom sign-up flow](https://clerk.com/docs/custom-flows/overview#sign-up-flow).
+ * The `useSignUp()` hook provides access to the [`SignUp`](https://clerk.com/docs/references/javascript/sign-up) object, which allows you to check the current state of a sign-up attempt and manage the sign-up flow. You can use this to create a [custom sign-up flow](https://clerk.com/docs/custom-flows/overview#sign-up-flow).
+ *
+ * @unionReturnHeadings
+ * ["Initialization", "Loaded"]
  *
  * @example
  * ### Check the current state of a sign-up
  *
- * The following example uses the `useSignUp()` hook to access the [`SignUp`](https://clerk.com/docs/references/javascript/sign-up/sign-up) object, which contains the current sign-up attempt status and methods to create a new sign-up attempt. The `isLoaded` property is used to handle the loading state.
+ * The following example uses the `useSignUp()` hook to access the [`SignUp`](https://clerk.com/docs/references/javascript/sign-up) object, which contains the current sign-up attempt status and methods to create a new sign-up attempt. The `isLoaded` property is used to handle the loading state.
  *
  * <Tabs items='React,Next.js'>
  * <Tab>

packages/shared/src/react/hooks/useSession.ts

@@ -8,6 +8,9 @@ type UseSession = (options?: PendingSessionOptions) => UseSessionReturn;
 /**
  * The `useSession()` hook provides access to the current user's [`Session`](https://clerk.com/docs/references/javascript/session) object, as well as helpers for setting the active session.
  *
+ * @unionReturnHeadings
+ * ["Initialization", "Signed out", "Signed in"]
+ *
  * @function
  *
  * @example

packages/shared/src/react/hooks/useSessionList.ts

@@ -5,6 +5,9 @@ import { useAssertWrappedByClerkProvider, useClerkInstanceContext, useClientCont
 /**
  * The `useSessionList()` hook returns an array of [`Session`](https://clerk.com/docs/references/javascript/session) objects that have been registered on the client device.
  *
+ * @unionReturnHeadings
+ * ["Initialization", "Loaded"]
+ *
  * @function
  *
  * @example

packages/shared/src/react/hooks/useUser.ts

@@ -5,6 +5,9 @@ import { useAssertWrappedByClerkProvider, useUserContext } from '../contexts';
 /**
  * The `useUser()` hook provides access to the current user's [`User`](https://clerk.com/docs/references/javascript/user) object, which contains all the data for a single user in your application and provides methods to manage their account. This hook also allows you to check if the user is signed in and if Clerk has loaded and initialized.
  *
+ * @unionReturnHeadings
+ * ["Initialization", "Signed out", "Signed in"]
+ *
  * @example
  * ### Get the current user
  *