chore(repo): Remove unused Typedoc blockTags

.changeset/chatty-dolls-work.md

@@ -0,0 +1,9 @@
+---
+'@clerk/clerk-js': patch
+'@clerk/elements': patch
+'@clerk/backend': patch
+'@clerk/nextjs': patch
+'@clerk/shared': patch
+---
+
+Improve JSDoc comments

docs/CONTRIBUTING.md

@@ -98,6 +98,71 @@ Updating documentation is an important part of the contribution process. If you
 
 To improve the in-editor experience when using Clerk's SDKs, we do our best to add [JSDoc comments](https://jsdoc.app/about-getting-started.html) to our package's public exports. The JSDoc comments should not attempt to duplicate any existing type information, but should provide meaningful additional context or references. If you are adding a new export, make sure it has a JSDoc comment. If you are updating an existing export, make sure any existing comments are updated appropriately.
 
+There are some styleguide decisions you should follow when authoring JSDoc comments:
+
+- In addition to the description, also annotate the parameters and return types (if applicable)
+- Provide one or more `@example` if you're documenting a function
+  - Use `###` (h3) headings and a description for each example
+- When using links, make sure that they are **absolute** links (e.g. `[Clerk docs](https://clerk.com/docs)`).
+- Provide a `@default` annotation when describing an optional property that will receive a default value
+- Follow the `clerk-docs` styleguides on [code blocks](https://github.com/clerk/clerk-docs/blob/main/CONTRIBUTING.md#code-blocks), [callouts](https://github.com/clerk/clerk-docs/blob/main/CONTRIBUTING.md#callouts)
+
+Here's an example of an excellent documented function that showcases the different styleguide instructions:
+
+````ts
+type FnParameters = {
+  /**
+   * Input to the function with a lengthy and good description.
+   */
+  input: string | Array<string>;
+  /**
+   * Optional parameter with a default value.
+   * @default false
+   */
+  isOffline?: boolean;
+};
+
+type FnReturn = Array<string>;
+
+/**
+ * Some long description goes here.
+ *
+ * > [!NOTE]
+ * > This is a note that will be rendered in the documentation.
+ *
+ * @example
+ * ### Example 1
+ *
+ * This shows how to use the function with a single string input.
+ *
+ * ```tsx
+ * const result = exampleFunction({ input: 'example' });
+ * console.log(result); // Output: ['example']
+ * ```
+ *
+ * @example
+ * ### Example 2
+ *
+ * This shows how to use the function with an array of strings as input.
+ *
+ * ```tsx
+ * const result = exampleFunction({ input: ['example1', 'example2'] });
+ * console.log(result); // Output: ['example1', 'example2']
+ * ```
+ */
+export function exampleFunction({ input, isOffline = false }: FnParameters): FnReturn {
+  if (isOffline) {
+    return [];
+  }
+
+  if (Array.isArray(input)) {
+    return input;
+  }
+
+  return [input];
+}
+````
+
 ### Writing tests
 
 When changing functionality or adding completely new code it's highly recommended to add/edit tests to verify the new behavior.

packages/backend/src/tokens/types.ts

@@ -57,8 +57,8 @@ export type OrganizationSyncOptions = {
    *
    * Patterns must have a path parameter named either `:id` (to match a Clerk organization ID) or `:slug` (to match a Clerk organization slug).
    *
-   * @warning
-   * If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
+   * > [!WARNING]
+   * > If the organization can't be activated—either because it doesn't exist or the user lacks access—the previously active organization will remain unchanged. Components must detect this case and provide an appropriate error and/or resolution pathway, such as calling `notFound()` or displaying an [`<OrganizationSwitcher />`](https://clerk.com/docs/components/organization/organization-switcher).
    *
    * @example
    * ["/orgs/:slug", "/orgs/:slug/(.*)"]

packages/clerk-js/src/core/errors.ts

@@ -3,10 +3,10 @@ const errorPrefix = 'ClerkJS:';
 /**
  * Used to log a warning when a Clerk feature is used in an unsupported environment.
  * (Development Only)
+ * This is a warning and not an error because the application will still work, but the feature will not be available.
  *
  * @param strategy The strategy that is not supported in the current environment.
  * @returns void
- * @note This is a warning and not an error because the application will still work, but the feature will not be available.
  */
 export function clerkUnsupportedEnvironmentWarning(strategy: string) {
   console.warn(`${errorPrefix} ${strategy} is not supported in this environment.`);

packages/elements/src/internals/machines/form/form.context.ts

@@ -34,9 +34,9 @@ type MapValue<A> = A extends Map<any, infer V> ? V : never;
 /**
  * Selects field-specific feedback, if they exist
  *
- * @note We declare an explicit return type here because TypeScript's inference results in the subtype reduction of the
- *       union used for feedback. Explicitly declaring the return type allows for all members of the union to be
- *       included in the return type.
+ * We declare an explicit return type here because TypeScript's inference results in the subtype reduction of the
+ * union used for feedback. Explicitly declaring the return type allows for all members of the union to be
+ * included in the return type.
  */
 export const fieldFeedbackSelector =
   (name: string | undefined) =>

packages/elements/src/react/sign-in/action/resend.tsx

@@ -25,11 +25,14 @@ const SIGN_IN_RESEND_NAME = 'SignInResend';
  * Resend verification codes during the sign-in process.
  * This component must be used within the <Step name="verifications">.
  *
- * @note This component is not intended to be used directly. Instead, use the <Action resend> component.
+ * > [!NOTE]
+ * > This component is not intended to be used directly. Instead, use the `<Action resend>` component.
  *
  * @example
+ * ```tsx
  * import { Action } from '@clerk/elements/sign-in';
  * <Action resend fallback={({ resendableAfter }) => <p>Resendable in: {resendableAfter}s</p>}>Resend</Action>;
+ * ```
  */
 export const SignInResend = React.forwardRef<SignInResendElement, SignInResendProps>(
   ({ asChild, fallback, ...rest }, forwardedRef) => {

packages/elements/src/react/sign-up/action/resend.tsx

@@ -25,11 +25,14 @@ const SIGN_UP_RESEND_NAME = 'SignUpResend';
  * Resend verification codes during the sign-in process.
  * This component must be used within the <Step name="verifications">.
  *
- * @note This component is not intended to be used directly. Instead, use the <Action resend> component.
+ * > [!NOTE]
+ * > This component is not intended to be used directly. Instead, use the `<Action resend>` component.
  *
  * @example
+ * ```tsx
  * import { Action } from '@clerk/elements/sign-in';
  * <Action resend fallback={({ resendableAfter }) => <p>Resendable in: {resendableAfter}s</p>}>Resend</Action>;
+ * ```
  */
 export const SignUpResend = React.forwardRef<SignUpResendElement, SignUpResendProps>(
   ({ asChild, fallback, ...rest }, forwardedRef) => {

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

@@ -21,8 +21,8 @@ type Auth = AuthObject & {
    *
    * @param [returnBackUrl] {string | URL} - The URL to redirect the user back to after they sign in.
    *
-   * @note
-   * `auth()` on the server-side can only access redirect URLs defined via [environment variables](https://clerk.com/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) or [`clerkMiddleware` dynamic keys](https://clerk.com/docs/references/nextjs/clerk-middleware#dynamic-keys).
+   * > [!NOTE]
+   * > `auth()` on the server-side can only access redirect URLs defined via [environment variables](https://clerk.com/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) or [`clerkMiddleware` dynamic keys](https://clerk.com/docs/references/nextjs/clerk-middleware#dynamic-keys).
    */
   redirectToSignIn: RedirectFun<ReturnType<typeof redirect>>;
 
@@ -31,8 +31,8 @@ type Auth = AuthObject & {
    *
    * @param [returnBackUrl] {string | URL} - The URL to redirect the user back to after they sign up.
    *
-   * @note
-   * `auth()` on the server-side can only access redirect URLs defined via [environment variables](https://clerk.com/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) or [`clerkMiddleware` dynamic keys](https://clerk.com/docs/references/nextjs/clerk-middleware#dynamic-keys).
+   * > [!NOTE]
+   * > `auth()` on the server-side can only access redirect URLs defined via [environment variables](https://clerk.com/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) or [`clerkMiddleware` dynamic keys](https://clerk.com/docs/references/nextjs/clerk-middleware#dynamic-keys).
    */
   redirectToSignUp: RedirectFun<ReturnType<typeof redirect>>;
 };
@@ -53,8 +53,8 @@ export interface AuthFn {
    * | Yes | No | Return a `404` error. |
    * | No | No | Redirect the user to the sign-in page\*. |
    *
-   * @important
-   * \*For non-document requests, such as API requests, `auth.protect()` returns a `404` error to users who aren't authenticated.
+   * > [!IMPORTANT]
+   * > \*For non-document requests, such as API requests, `auth.protect()` returns a `404` error to users who aren't authenticated.
    *
    * `auth.protect()` can be used to check if a user is authenticated or authorized to access certain parts of your application or even entire routes. See detailed examples in the [dedicated guide](https://clerk.com/docs/organizations/verify-user-permissions).
    */

packages/nextjs/src/server/createGetAuth.ts

@@ -75,8 +75,8 @@ export const createSyncGetAuth = ({
 /**
  * The `getAuth()` helper retrieves authentication state from the request object.
  *
- * @note
- * If you are using App Router, use the [`auth()` helper](https://clerk.com/docs/references/nextjs/auth) instead.
+ * > [!NOTE]
+ * > If you are using App Router, use the [`auth()` helper](https://clerk.com/docs/references/nextjs/auth) instead.
  *
  * @param req - The Next.js request object.
  * @param [options] - An optional object that can be used to configure the behavior of the `getAuth()` function.

packages/shared/src/error.ts

@@ -164,15 +164,13 @@ export class ClerkRuntimeError extends Error {
    * The error message.
    *
    * @type {string}
-   * @memberof ClerkRuntimeError
    */
   message: string;
 
   /**
    * A unique code identifying the error, can be used for localization.
    *
    * @type {string}
-   * @memberof ClerkRuntimeError
    */
   code: string;
 
@@ -195,7 +193,6 @@ export class ClerkRuntimeError extends Error {
    * Returns a string representation of the error.
    *
    * @returns {string} A formatted string with the error name and message.
-   * @memberof ClerkRuntimeError
    */
   public toString = () => {
     return `[${this.name}]\nMessage:${this.message}`;

typedoc.config.mjs

@@ -95,7 +95,7 @@ const config = {
     excludeInternal: true,
     excludeNotDocumented: true,
     gitRevision: 'main',
-    blockTags: [...OptionDefaults.blockTags, '@warning', '@note', '@important', '@memberof'],
+    blockTags: [...OptionDefaults.blockTags],
     modifierTags: [...OptionDefaults.modifierTags],
     exclude: ['src/**/*.test.ts', 'src/**/*.test.tsx'],
     readme: 'none',