chore(repo): Use markdown plugin for typedoc (#5099)

Author: LekoArts

.changeset/late-bags-hang.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': patch
+'@clerk/types': patch
+---
+
+Small JSDoc and type improvements

package.json

@@ -128,7 +128,7 @@
     "turbo": "^2.0.14",
     "turbo-ignore": "^2.0.6",
     "typedoc": "0.27.6",
-    "typedoc-plugin-missing-exports": "3.1.0",
+    "typedoc-plugin-markdown": "4.4.1",
     "typescript": "catalog:repo",
     "typescript-eslint": "8.21.0",
     "uuid": "8.3.2",

packages/shared/src/telemetry/throttler.ts

@@ -48,7 +48,7 @@ export class TelemetryEventThrottler {
   #generateKey(event: TelemetryEvent): string {
     const { sk: _sk, pk: _pk, payload, ...rest } = event;
 
-    const sanitizedEvent = {
+    const sanitizedEvent: Omit<TelemetryEvent, 'sk' | 'pk' | 'payload'> & TelemetryEvent['payload'] = {
       ...payload,
       ...rest,
     };

packages/shared/typedoc.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["./src/index.ts", "./src/react/index.ts"],
+  "compilerOptions": {
+    "noImplicitAny": false
+  }
+}

packages/types/src/hooks.ts

@@ -17,6 +17,7 @@ type CheckAuthorizationWithoutOrgOrUser = (params: Parameters<CheckAuthorization
 
 /**
  * Return values of the `useAuth()` hook
+ * @interface
  */
 export type UseAuthReturn =
   | {
@@ -63,137 +64,48 @@ export type UseAuthReturn =
       getToken: GetToken;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * A boolean that indicates whether a user is currently signed in.
-       */
       isSignedIn: false;
-      /**
-       * The ID of the current user.
-       */
       userId: null;
-      /**
-       * The ID for the current session.
-       */
       sessionId: null;
       actor: null;
-      /**
-       * The ID of the user's active organization.
-       */
       orgId: null;
-      /**
-       * The current user's role in their active organization.
-       */
       orgRole: null;
-      /**
-       * The URL-friendly identifier of the user's active organization.
-       */
       orgSlug: null;
-      /**
-       * A function that checks if the user has specific permissions or roles. See the [reference doc](https://clerk.com/docs/references/backend/types/auth-object#has).
-       */
       has: CheckAuthorizationWithoutOrgOrUser;
-      /**
-       * A function that signs out the current user. Returns a promise that resolves when complete. See the [reference doc](https://clerk.com/docs/references/javascript/clerk/clerk#sign-out).
-       */
       signOut: SignOut;
-      /**
-       * A function that retrieves the current user's session token or a custom JWT template. Returns a promise that resolves to the token. See the [reference doc](https://clerk.com/docs/references/javascript/session#get-token).
-       */
       getToken: GetToken;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * A boolean that indicates whether a user is currently signed in.
-       */
       isSignedIn: true;
-      /**
-       * The ID of the current user.
-       */
       userId: string;
-      /**
-       * The ID for the current session.
-       */
       sessionId: string;
       actor: ActJWTClaim | null;
-      /**
-       * The ID of the user's active organization.
-       */
       orgId: null;
-      /**
-       * The current user's role in their active organization.
-       */
       orgRole: null;
-      /**
-       * The URL-friendly identifier of the user's active organization.
-       */
       orgSlug: null;
-      /**
-       * A function that checks if the user has specific permissions or roles. See the [reference doc](https://clerk.com/docs/references/backend/types/auth-object#has).
-       */
       has: CheckAuthorizationWithCustomPermissions;
-      /**
-       * A function that signs out the current user. Returns a promise that resolves when complete. See the [reference doc](https://clerk.com/docs/references/javascript/clerk/clerk#sign-out).
-       */
       signOut: SignOut;
-      /**
-       * A function that retrieves the current user's session token or a custom JWT template. Returns a promise that resolves to the token. See the [reference doc](https://clerk.com/docs/references/javascript/session#get-token).
-       */
       getToken: GetToken;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * A boolean that indicates whether a user is currently signed in.
-       */
       isSignedIn: true;
-      /**
-       * The ID of the current user.
-       */
       userId: string;
-      /**
-       * The ID for the current session.
-       */
       sessionId: string;
       actor: ActJWTClaim | null;
-      /**
-       * The ID of the user's active organization.
-       */
       orgId: string;
-      /**
-       * The current user's role in their active organization.
-       */
       orgRole: OrganizationCustomRoleKey;
-      /**
-       * The URL-friendly identifier of the user's active organization.
-       */
       orgSlug: string | null;
-      /**
-       * A function that checks if the user has specific permissions or roles. See the [reference doc](https://clerk.com/docs/references/backend/types/auth-object#has).
-       */
       has: CheckAuthorizationWithCustomPermissions;
-      /**
-       * A function that signs out the current user. Returns a promise that resolves when complete. See the [reference doc](https://clerk.com/docs/references/javascript/clerk/clerk#sign-out).
-       */
       signOut: SignOut;
-      /**
-       * A function that retrieves the current user's session token or a custom JWT template. Returns a promise that resolves to the token. See the [reference doc](https://clerk.com/docs/references/javascript/session#get-token).
-       */
       getToken: GetToken;
     };
 
 /**
  * Return values of the `useSignIn()` hook
+ * @interface
  */
 export type UseSignInReturn =
   | {
@@ -211,22 +123,14 @@ export type UseSignInReturn =
       setActive: undefined;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * An object that contains the current sign-in attempt status and methods to create a new sign-in attempt.
-       */
       signIn: SignInResource;
-      /**
-       * A function that sets the active session.
-       */
       setActive: SetActive;
     };
 
 /**
  * Return values of the `useSignUp()` hook
+ * @interface
  */
 export type UseSignUpReturn =
   | {
@@ -244,22 +148,14 @@ export type UseSignUpReturn =
       setActive: undefined;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * An object that contains the current sign-up attempt status and methods to create a new sign-up attempt.
-       */
       signUp: SignUpResource;
-      /**
-       * A function that sets the active session.
-       */
       setActive: SetActive;
     };
 
 /**
  * Return values of the `useSession()` hook
+ * @interface
  */
 export type UseSessionReturn =
   | {
@@ -277,36 +173,19 @@ export type UseSessionReturn =
       session: undefined;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * A boolean that indicates whether a user is currently signed in.
-       */
       isSignedIn: false;
-      /**
-       * Holds the current active session for the user.
-       */
       session: null;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * A boolean that indicates whether a user is currently signed in.
-       */
       isSignedIn: true;
-      /**
-       * Holds the current active session for the user.
-       */
       session: ActiveSessionResource;
     };
 
 /**
  * Return values of the `useSessionList()` hook
+ * @interface
  */
 export type UseSessionListReturn =
   | {
@@ -324,22 +203,14 @@ export type UseSessionListReturn =
       setActive: undefined;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * A list of sessions that have been registered on the client device.
-       */
       sessions: SessionResource[];
-      /**
-       * A function that sets the active session and/or organization.
-       */
       setActive: SetActive;
     };
 
 /**
  * Return values of the `useUser()` hook
+ * @interface
  */
 export type UseUserReturn =
   | {
@@ -358,26 +229,11 @@ export type UseUserReturn =
     }
   | {
       isLoaded: true;
-      /**
-       * A boolean that indicates whether a user is currently signed in.
-       */
       isSignedIn: false;
-      /**
-       * The `User` object for the current user. If the user isn't signed in, `user` will be `null`.
-       */
       user: null;
     }
   | {
-      /**
-       * A boolean that indicates whether Clerk has completed initialization. Initially `false`, becomes `true` once Clerk loads.
-       */
       isLoaded: true;
-      /**
-       * A boolean that indicates whether a user is currently signed in.
-       */
       isSignedIn: true;
-      /**
-       * The `User` object for the current user. If the user isn't signed in, `user` will be `null`.
-       */
       user: UserResource;
     };

pnpm-lock.yaml

@@ -23,13 +23,20 @@ function getPackages() {
   return packages.filter(dir => !IGNORE_LIST.includes(dir)).map(dir => path.join('packages', dir));
 }
 
+/** @type {import("typedoc-plugin-markdown").PluginOptions} */
+const typedocPluginMarkdownOptions = {
+  hidePageHeader: true,
+  hideBreadcrumbs: true,
+  hidePageTitle: true,
+};
+
 /** @type {Partial<import("typedoc").TypeDocOptions>} */
 const config = {
   out: './.typedoc/docs',
   // TODO: Once we're happy with the output the JSON should be written to a non-gitignored location as we want to consume it in other places
   json: './.typedoc/output.json',
   entryPointStrategy: 'packages',
-  plugin: ['typedoc-plugin-missing-exports'],
+  plugin: ['typedoc-plugin-markdown'],
   packageOptions: {
     includeVersion: false,
     excludePrivate: true,
@@ -39,11 +46,15 @@ const config = {
     excludeInternal: true,
     excludeNotDocumented: true,
     gitRevision: 'main',
-    blockTags: [...OptionDefaults.blockTags, '@warning', '@note', '@important'],
+    blockTags: [...OptionDefaults.blockTags, '@warning', '@note', '@important', '@memberof'],
     modifierTags: [...OptionDefaults.modifierTags],
     exclude: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
+    readme: 'none',
+    disableGit: true,
+    disableSources: true,
   },
-  entryPoints: ['packages/nextjs', 'packages/react', 'packages/backend', 'packages/types'], // getPackages(),
+  entryPoints: ['packages/nextjs', 'packages/react', 'packages/shared', 'packages/types'], // getPackages(),
+  ...typedocPluginMarkdownOptions,
 };
 
 export default config;