clerk · SarahSoutoul · Jul 21, 2026 · Jul 20, 2026 · Jul 20, 2026 · Jul 20, 2026
diff --git a/.changeset/eg-ie-trailing-comma-jsdoc.md b/.changeset/eg-ie-trailing-comma-jsdoc.md
@@ -0,0 +1,6 @@
+---
+'@clerk/backend': patch
+'@clerk/shared': patch
+---
+
+Standardize JSDoc punctuation to always follow `e.g.` and `i.e.` with a comma (`e.g.,` / `i.e.,`), matching the docs style guide. Comment-only change; no runtime behavior is affected. This keeps the generated Typedoc reference output consistent.
diff --git a/.typedoc/__tests__/__snapshots__/clerk-properties.mdx b/.typedoc/__tests__/__snapshots__/clerk-properties.mdx
@@ -9,7 +9,7 @@
 | <a id="issignedin"></a> `isSignedIn`               | `boolean`                                                                                            | Indicates whether the current user has a valid signed-in client session.                                                                                                                                                                                                                                                                 |
 | <a id="isstandardbrowser"></a> `isStandardBrowser` | <code>undefined \| boolean</code>                                                                    | Indicates whether the instance is being loaded in a standard browser environment. Set to `false` on native platforms where cookies cannot be set. When `undefined`, Clerk assumes a standard browser.                                                                                                                                    |
 | <a id="loaded"></a> `loaded`                       | `boolean`                                                                                            | Indicates whether the `Clerk` object is ready for use. Set to `false` when the `status` is `"loading"`. Set to `true` when the `status` is `"ready"` or `"degraded"`.                                                                                                                                                                    |
-| <a id="oauthapplication"></a> `oauthApplication`   | [`OAuthApplicationNamespace`](/docs/reference/types/oauth-application)                               | OAuth application helpers (e.g. consent metadata for custom consent UIs).                                                                                                                                                                                                                                                                |
+| <a id="oauthapplication"></a> `oauthApplication`   | [`OAuthApplicationNamespace`](/docs/reference/types/oauth-application)                               | OAuth application helpers (e.g., consent metadata for custom consent UIs).                                                                                                                                                                                                                                                               |
 | <a id="organization"></a> `organization`           | <code>undefined \| null \| [OrganizationResource](/docs/reference/objects/organization)</code>       | A shortcut to the last active `Session.user.organizationMemberships` which holds an instance of a `Organization` object. If the session is `null` or `undefined`, the user field will match.                                                                                                                                             |
 | <a id="proxyurl"></a> `proxyUrl`                   | <code>undefined \| string</code>                                                                     | **Required for applications that run behind a reverse proxy**. Your Clerk app's proxy URL. Can be either a relative path (`/__clerk`) or a full URL (`https://<your-domain>/__clerk`).                                                                                                                                                   |
 | <a id="publishablekey"></a> `publishableKey`       | `string`                                                                                             | Your Clerk [Publishable Key](!publishable-key).                                                                                                                                                                                                                                                                                          |

diff --git a/packages/backend/src/api/endpoints/AgentTaskApi.ts b/packages/backend/src/api/endpoints/AgentTaskApi.ts
@@ -4,7 +4,7 @@ import { AbstractAPI } from './AbstractApi';
 
 /** @generateWithEmptyComment */
 export type CreateAgentTaskParams = {
-  /** The user to create an Agent Task for. Provide either a `userId` or an `identifier` (e.g. an email address, phone number, or username). */
+  /** The user to create an Agent Task for. Provide either a `userId` or an `identifier` (e.g., an email address, phone number, or username). */
   onBehalfOf:
     | {
         /** The identifier of the user to create an Agent Task for. */

diff --git a/packages/backend/src/api/endpoints/AllowlistIdentifierApi.ts b/packages/backend/src/api/endpoints/AllowlistIdentifierApi.ts
@@ -10,7 +10,7 @@ const basePath = '/allowlist_identifiers';
 
 /** @generateWithEmptyComment */
 export type AllowlistIdentifierCreateParams = {
-  /** The identifier to add to the allowlist. Can be an email address, a domain in wildcard email format (e.g. `*@example.com`), a phone number in international E.164 format (e.g. `+15555555555`), or a Web3 wallet address. */
+  /** The identifier to add to the allowlist. Can be an email address, a domain in wildcard email format (e.g., `*@example.com`), a phone number in international E.164 format (e.g., `+15555555555`), or a Web3 wallet address. */
   identifier: string;
   /** Whether to notify the user that their identifier has been added to the allowlist. Notifies the user if the `identifier` is an email address or phone number. */
   notify: boolean;

diff --git a/packages/backend/src/api/endpoints/DomainApi.ts b/packages/backend/src/api/endpoints/DomainApi.ts
@@ -9,7 +9,7 @@ const basePath = '/domains';
 /** @generateWithEmptyComment */
 export type AddDomainParams = {
   /**
-   * The new domain name. For development instances, can contain the port, e.g. `myhostname:3000`. For production instances, must be a valid FQDN, e.g. `mysite.com`. Cannot contain protocol scheme.
+   * The new domain name. For development instances, can contain the port, e.g., `myhostname:3000`. For production instances, must be a valid FQDN, e.g., `mysite.com`. Cannot contain protocol scheme.
    */
   name: string;
   /** Whether the new domain is a satellite domain. Only `true` is accepted at the moment. */

diff --git a/packages/backend/src/api/endpoints/InstanceApi.ts b/packages/backend/src/api/endpoints/InstanceApi.ts
@@ -22,7 +22,7 @@ export type UpdateParams = {
   developmentOrigin?: string | null | undefined;
   /** For browser-like stacks such as browser extensions, Electron, or Capacitor.js, the instance allowed origins need to be updated with the request origin value. For Chrome extensions popup, background, or service worker pages the origin is `chrome-extension://extension_uiid`. For Electron apps the default origin is `http://localhost:3000`. For Capacitor.js, the origin is `capacitor://localhost`. */
   allowedOrigins?: Array<string> | undefined;
-  /** Whether the instance should use URL-based session syncing in development mode (i.e. without third-party cookies). */
+  /** Whether the instance should use URL-based session syncing in development mode (i.e., without third-party cookies). */
   urlBasedSessionSyncing?: boolean | null | undefined;
   /** Overrides the sign-in strategy that is preferred when a password is required. The value is only consulted when a password is required, and is dormant otherwise. Pass an empty string to clear the override. Passing `null` or `undefined` leaves the current value unchanged. */
   preferredSignInStrategyWhenPasswordRequired?: 'password' | 'otp' | '' | null | undefined;

diff --git a/packages/backend/src/api/endpoints/InvitationApi.ts b/packages/backend/src/api/endpoints/InvitationApi.ts
@@ -121,7 +121,7 @@ export class InvitationAPI extends AbstractAPI {
    *
    * Revoking an invitation makes the invitation email link unusable. However, it doesn't prevent the user from signing up if they follow the sign up flow.
    *
-   * Only active (i.e. non-revoked) invitations can be revoked.
+   * Only active (i.e., non-revoked) invitations can be revoked.
    * @param invitationId - The ID of the invitation to revoke.
    * @returns The revoked [`Invitation`](https://clerk.com/docs/reference/backend/types/backend-invitation).
    */

diff --git a/packages/backend/src/api/endpoints/UserApi.ts b/packages/backend/src/api/endpoints/UserApi.ts
@@ -245,15 +245,15 @@ export type CreateUserParams = {
   firstName?: string;
   /** The last name to assign to the user. */
   lastName?: string;
-  /** The locale of the user in BCP-47 format (e.g. `'en-US'`, `'fr-FR'`). */
+  /** The locale of the user in BCP-47 format (e.g., `'en-US'`, `'fr-FR'`). */
   locale?: string;
   /** When set to `true`, all password checks are skipped. It is recommended to use this method only when migrating plaintext passwords to Clerk. Upon migration the user base should be prompted to pick stronger password. */
   skipPasswordChecks?: boolean;
   /** When set to `true`, password is not required anymore when creating the user and can be omitted. This is useful when you are trying to create a user that doesn't have a password, in an instance that is using passwords. **You cannot use this flag if password is the only way for a user to sign into your instance.** */
   skipPasswordRequirement?: boolean;
   /** When set to `true`, all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk. */
   skipLegalChecks?: boolean;
-  /** A custom timestamp denoting when the user accepted legal requirements, specified in RFC3339 format (e.g. `'2012-10-20T07:15:20.902Z'`). */
+  /** A custom timestamp denoting when the user accepted legal requirements, specified in RFC3339 format (e.g., `'2012-10-20T07:15:20.902Z'`). */
   legalAcceptedAt?: Date;
   /**
    * If TOTP is enabled on the instance, you can provide the secret to enable it on the newly created user without the need to reset it. Currently, the supported options are:
@@ -266,7 +266,7 @@ export type CreateUserParams = {
   totpSecret?: string;
   /** If backup codes are enabled on the instance, you can provide them to enable it on the newly created user without the need to reset them. You must provide the backup codes in plain format or the corresponding bcrypt digest. */
   backupCodes?: string[];
-  /** A custom timestamp denoting when the user signed up to the application, specified in RFC3339 format (e.g. `'2012-10-20T07:15:20.902Z'`). */
+  /** A custom timestamp denoting when the user signed up to the application, specified in RFC3339 format (e.g., `'2012-10-20T07:15:20.902Z'`). */
   createdAt?: Date;
   /** When set to `true`, the user is created already banned and cannot sign in. */
   banned?: boolean;
@@ -312,13 +312,13 @@ export type UpdateUserParams = {
   backupCodes?: string[];
   /** The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your entire instance. */
   externalId?: string;
-  /** A custom timestamp denoting when the user signed up to the application, specified in RFC3339 format (e.g. `'2012-10-20T07:15:20.902Z'`). */
+  /** A custom timestamp denoting when the user signed up to the application, specified in RFC3339 format (e.g., `'2012-10-20T07:15:20.902Z'`). */
   createdAt?: Date;
   /** When set to `true`, all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk. */
   skipLegalChecks?: boolean;
-  /** A custom timestamp denoting when the user accepted legal requirements, specified in RFC3339 format (e.g. `'2012-10-20T07:15:20.902Z'`). */
+  /** A custom timestamp denoting when the user accepted legal requirements, specified in RFC3339 format (e.g., `'2012-10-20T07:15:20.902Z'`). */
   legalAcceptedAt?: Date;
-  /** The locale of the user in BCP-47 format (e.g. `'en-US'`). */
+  /** The locale of the user in BCP-47 format (e.g., `'en-US'`). */
   locale?: string;
   /** If `true`, the user can delete themselves with the Frontend API. */
   deleteSelfEnabled?: boolean;
@@ -620,7 +620,7 @@ export class UserAPI extends AbstractAPI {
   /**
    * Gets the corresponding [OAuth access token](!oauth-access-token) for a user that has previously authenticated with the given OAuth provider.
    * @param userId - The ID of the user to get the OAuth access tokens for.
-   * @param provider - The OAuth provider to get the access tokens for. If using a custom OAuth provider, prefix the provider name with `custom_` (e.g. `oauth_custom_google`).
+   * @param provider - The OAuth provider to get the access tokens for. If using a custom OAuth provider, prefix the provider name with `custom_` (e.g., `oauth_custom_google`).
    * @returns A [`PaginatedResourceResponse`](https://clerk.com/docs/reference/backend/types/paginated-resource-response) object with a `data` property that contains an array of [`OauthAccessToken`](https://clerk.com/docs/reference/backend/types/backend-oauth-access-token) objects, and a `totalCount` property that indicates the total number of OAuth access tokens for the specified user and provider.
    */
   public async getUserOauthAccessToken(
@@ -652,7 +652,7 @@ export class UserAPI extends AbstractAPI {
   }
 
   /**
-   * Disable all of a user's MFA methods (e.g. [OTP](!otp) sent via SMS, TOTP on their authenticator app) at once.
+   * Disable all of a user's MFA methods (e.g., [OTP](!otp) sent via SMS, TOTP on their authenticator app) at once.
    * @param userId - The ID of the user to disable MFA for.
    */
   public async disableUserMFA(userId: string) {
@@ -705,7 +705,7 @@ export class UserAPI extends AbstractAPI {
     });
   }
 
-  /** Verify that the provided TOTP or backup code is valid for the user. Verifying a backup code will result it in being consumed (i.e. it will become invalid). Useful for custom auth flows and re-verification. */
+  /** Verify that the provided TOTP or backup code is valid for the user. Verifying a backup code will result it in being consumed (i.e., it will become invalid). Useful for custom auth flows and re-verification. */
   public async verifyTOTP(params: VerifyTOTPParams) {
     const { userId, code } = params;
     this.requireId(userId);

diff --git a/packages/backend/src/api/resources/ExternalAccount.ts b/packages/backend/src/api/resources/ExternalAccount.ts
@@ -2,7 +2,7 @@ import type { ExternalAccountJSON } from './JSON';
 import { Verification } from './Verification';
 
 /**
- * The Backend `ExternalAccount` object is a model around an identification obtained by an external provider (e.g. a social provider such as Google).
+ * The Backend `ExternalAccount` object is a model around an identification obtained by an external provider (e.g., a social provider such as Google).
  *
  * External account must be verified, so that you can make sure they can be assigned to their rightful owners. The `ExternalAccount` object holds all necessary state around the verification process.
  */

diff --git a/packages/backend/src/api/resources/RedirectUrl.ts b/packages/backend/src/api/resources/RedirectUrl.ts
@@ -1,7 +1,7 @@
 import type { RedirectUrlJSON } from './JSON';
 
 /**
- * Redirect URLs are whitelisted URLs that facilitate secure authentication flows in native applications (e.g. React Native, Expo). In these contexts, Clerk ensures that security-critical nonces are passed only to the whitelisted URLs.
+ * Redirect URLs are whitelisted URLs that facilitate secure authentication flows in native applications (e.g., React Native, Expo). In these contexts, Clerk ensures that security-critical nonces are passed only to the whitelisted URLs.
 
 The Backend `RedirectUrl` object represents a redirect URL in your application. This object is used in the Backend API.
  */

diff --git a/packages/backend/src/tokens/types.ts b/packages/backend/src/tokens/types.ts
@@ -163,7 +163,7 @@ export type OrganizationSyncTargetMatchers = {
 };
 
 /**
- * Represents an Organization or a Personal Account - e.g. an
+ * Represents an Organization or a Personal Account - i.e., an
  * entity that can be activated by the handshake API.
  */
 export type OrganizationSyncTarget =

diff --git a/packages/backend/src/tokens/verify.ts b/packages/backend/src/tokens/verify.ts
@@ -251,7 +251,7 @@ async function verifyAPIKey(
  * Verifies any type of machine token by detecting its type from the prefix or JWT claims.
  * For JWTs, decodes once and routes based on claims to avoid redundant decoding.
  *
- * @param token - The token to verify (e.g. starts with "mt_", "oat_", "ak_", or a JWT)
+ * @param token - The token to verify (e.g., starts with "mt_", "oat_", "ak_", or a JWT)
  * @param options - Options including secretKey for BAPI authorization
  */
 export async function verifyMachineAuthToken(token: string, options: VerifyTokenOptions) {

diff --git a/packages/shared/src/react/billing/payment-element.tsx b/packages/shared/src/react/billing/payment-element.tsx
@@ -307,7 +307,7 @@ export type UsePaymentElementReturn = {
         name: 'stripe';
       };
       /**
-       * Indicates whether the underlying payment provider (e.g. Stripe) has been fully initialized.
+       * Indicates whether the underlying payment provider (e.g., Stripe) has been fully initialized.
        */
       isProviderReady: true;
     }

diff --git a/packages/shared/src/react/contexts.tsx b/packages/shared/src/react/contexts.tsx
@@ -70,7 +70,7 @@ export type UseCheckoutOptions = {
    */
   planPeriod: BillingSubscriptionPlanPeriod;
   /**
-   * The ID of the Subscription Plan to check out (e.g. `cplan_xxx`).
+   * The ID of the Subscription Plan to check out (e.g., `cplan_xxx`).
    */
   planId: string;
   /**

diff --git a/packages/shared/src/react/hooks/useOAuthConsent.tsx b/packages/shared/src/react/hooks/useOAuthConsent.tsx
@@ -12,7 +12,7 @@ const HOOK_NAME = 'useOAuthConsent';
 /**
  * The `useOAuthConsent()` hook loads OAuth application consent metadata for the **signed-in** user
  * (`GET /me/oauth/consent/{oauthClientId}`). Ensure the user is authenticated before relying on this hook
- * (for example, redirect to sign-in on your custom consent route).
+ * (e.g., redirect to sign-in on your custom consent route).
  *
  * @example
  * ```tsx

diff --git a/packages/shared/src/react/hooks/useOrganization.tsx b/packages/shared/src/react/hooks/useOrganization.tsx
@@ -69,7 +69,7 @@ export type UseOrganizationParams = {
 export type UseOrganizationReturn<T extends UseOrganizationParams> =
   | {
       /**
-       * Indicates whether Clerk has loaded the current authentication state. Initially `false`, becomes `true` once Clerk loads, and can revert to `false` while auth state is updating (for example, when switching organizations via [`setActive()`](https://clerk.com/docs/reference/objects/clerk#set-active)).
+       * Indicates whether Clerk has loaded the current authentication state. Initially `false`, becomes `true` once Clerk loads, and can revert to `false` while auth state is updating (e.g., when switching organizations via [`setActive()`](https://clerk.com/docs/reference/objects/clerk#set-active)).
        */
       isLoaded: false;
       /**

diff --git a/packages/shared/src/react/hooks/useOrganizationList.tsx b/packages/shared/src/react/hooks/useOrganizationList.tsx
@@ -77,7 +77,7 @@ const undefinedPaginatedResource = {
 export type UseOrganizationListReturn<T extends UseOrganizationListParams> =
   | {
       /**
-       * Indicates whether Clerk has loaded the current authentication state and there is an authenticated user. Initially `false`, becomes `true` once Clerk loads with a user, and can revert to `false` while auth state is updating (for example, when switching organizations via [`setActive()`](https://clerk.com/docs/reference/objects/clerk#set-active)).
+       * Indicates whether Clerk has loaded the current authentication state and there is an authenticated user. Initially `false`, becomes `true` once Clerk loads with a user, and can revert to `false` while auth state is updating (e.g., when switching organizations via [`setActive()`](https://clerk.com/docs/reference/objects/clerk#set-active)).
        */
       isLoaded: false;
       /**