(javascript) update parameters and formatting of some references (#1912)

Co-authored-by: Vaggelis Yfantis <[email protected]>
Co-authored-by: victoria <[email protected]>

docs/references/javascript/clerk/clerk.mdx

@@ -32,14 +32,14 @@ The `Clerk` class is the main entrypoint class for the `@clerk/clerk-js` package
   - `domain`
   - `string`
 
-  A getter for the current Clerk app's domain.<br />Prefixed with `clerk.` on production if not already prefixed.<br />Returns `""` when ran on the server
+  A getter for the current Clerk app's domain. Prefixed with `clerk.` on production if not already prefixed. Returns `""` when ran on the server
 
   ---
 
   - `proxyUrl`
   - `string`
 
-  A getter for your Clerk app's proxy URL. Required for applications that run behind a reverse proxy.<br />Can be either a relative path (`/__clerk`) or a full URL (`https://<your-domain>/__clerk`).
+  A getter for your Clerk app's proxy URL. Required for applications that run behind a reverse proxy. Can be either a relative path (`/__clerk`) or a full URL (`https://<your-domain>/__clerk`).
 
   ---
 
@@ -148,14 +148,14 @@ function authenticateWithMetamask({
   - `redirectUrl?`
   - `string | undefined`
 
-  The full URL or path to navigate to after a successful sign in or sign up.
+  The full URL or path to navigate to after a successful sign-in or sign-up.
 
   ---
 
   - `signUpContinueUrl?`
   - `string | undefined`
 
-  The URL to navigate to in the sign-up process if data is missing.
+  The URL to navigate to if the sign-up process is missing user information.
 
   ---
 
@@ -181,14 +181,14 @@ function authenticateWithCoinbaseWallet({
   - `redirectUrl?`
   - `string | undefined`
 
-  The full URL or path to navigate to after a successful sign in or sign up.
+  The full URL or path to navigate to after a successful sign-in or sign-up.
 
   ---
 
   - `signUpContinueUrl?`
   - `string | undefined`
 
-  The full URL or path to navigate to in the sign-up process if data is missing.
+  The full URL or path to navigate to if the sign-up process is missing user information.
 
   ---
 
@@ -219,7 +219,7 @@ function authenticateWithOKXWallet(props?: AuthenticateWithOKXWalletParams): Pro
   - `signUpContinueUrl?`
   - `string | undefined`
 
-  The full URL or path to navigate to in the sign-up process if data is missing.
+  The full URL or path to navigate to if the sign-up process is missing user information.
 
   ---
 
@@ -240,7 +240,7 @@ function authenticateWithOKXWallet(props?: AuthenticateWithOKXWalletParams): Pro
   - `legalAccepted?`
   - `boolean`
 
-  The user has agreed to the [legal compliance](/docs/authentication/configuration/legal-compliance) documents.
+  A boolean indicating whether the user has agreed to the [legal compliance](/docs/authentication/configuration/legal-compliance) documents.
 </Properties>
 
 ### `authenticateWithWeb3()`
@@ -267,7 +267,7 @@ function authenticateWithWeb3({
   - `signUpContinueUrl?`
   - `string | undefined`
 
-  The full URL or path to navigate to in the sign-up process if data is missing.
+  The full URL or path to navigate to if the sign-up process is missing user information.
 
   ---
 

docs/references/javascript/clerk/handle-navigation.mdx

@@ -42,7 +42,7 @@ Take a look at the function parameters description below for more usage details.
   - `params`
   - [`handleEmailLinkVerificationParams`](#handle-email-link-verification-params)
 
-  Allows you to define the URLs where the user should be redirected to on successful verification and: <ul><li>Completed sign in or sign up attempt.</li><li>Pending sign in or sign up attempt.</li></ul><br />If the email link is successfully verified on another device, there's a callback function parameter that allows custom code execution.
+  Allows you to define the URLs where the user should be redirected to on successful verification or pending/completed sign-up or sign-in attempts. If the email link is successfully verified on another device, there's a callback function parameter that allows custom code execution.
 
   ---
 
@@ -58,14 +58,14 @@ Take a look at the function parameters description below for more usage details.
   - `redirectUrlComplete?`
   - `string | undefined`
 
-  Full URL or path to navigate after successful email link verification on completed sign up or sign in on the same device.
+  The full URL or path to navigate to after successful email link verification on completed sign-up or sign-in on the same device.
 
   ---
 
   - `redirectUrl?`
   - `string | undefined`
 
-  Full URL or path to navigate after successful email link verification on the same device, but not completed sign in or sign up.
+  The full URL or path to navigate to after successful email link verification on the same device, but without completing sign-in or sign-up.
 
   ---
 

docs/references/javascript/email-address.mdx

@@ -80,14 +80,17 @@ function prepareVerification(params: PrepareEmailAddressVerificationParams): Pro
   - `strategy`
   - `'email_link' | 'email_code'`
 
-  The verification strategy.<br />Possible strategy values are:<br /><ul><li>`email_link`: User will receive an email link via email.</li><li>`email_code`: User will receive a one-time authentication code via email.</li></ul>
+  The verification strategy. Supported strategies are:
+
+  - `email_link`: User will receive an email link via email.
+  - `email_code`: User will receive a one-time authentication code via email.
 
   ---
 
   - `redirectUrl`
   - `string | undefined`
 
-  The email link target URL. Users will be redirected here once they click the email link from their email. This param only applies if `strategy` is `email_link`.
+  **Required** if `strategy` is set to `email_link`. The URL that the user will be redirected to when they visit the email link. See the [custom flow](/docs/custom-flows/email-links) for implementation details.
 </Properties>
 
 ### `attemptVerification()`
@@ -146,5 +149,5 @@ function createEmailLinkFlow(): {
   - `redirectUrl`
   - `string`
 
-  The email link target URL. Users will be redirected here once they click the email link from their email.
+  The URL that the user will be redirected to when they visit the email link.
 </Properties>

docs/references/javascript/external-account.mdx

@@ -27,7 +27,7 @@ External account must be verified, so that you can make sure they can be assigne
   - `provider`
   - `string`
 
-  The provider name e.g. `google`
+  The provider name (e.g., `google`).
 
   ---
 
@@ -41,7 +41,7 @@ External account must be verified, so that you can make sure they can be assigne
   - `emailAddress`
   - `string`
 
-  The provided email address of the user.
+  The user's email address.
 
   ---
 
@@ -55,28 +55,28 @@ External account must be verified, so that you can make sure they can be assigne
   - `firstName`
   - `string`
 
-  The provided first name of the user.
+  The user's first name.
 
   ---
 
   - `lastName`
   - `string`
 
-  The provided last name of the user.
+  The user's last name.
 
   ---
 
   - `imageUrl`
   - `string`
 
-  The provided image URL of the user.
+  The user's image URL.
 
   ---
 
   - `username`
   - `string | null`
 
-  The provided username of the user.
+  The user's username.
 
   ---
 
@@ -116,14 +116,14 @@ function reauthorize(params: ReauthorizeExternalAccountParams): Promise<External
   - `additionalScopes`
   - `string[]`
 
-  Any additional scopes you would like your user to be prompted to approve.
+  Additional scopes for your user to be prompted to approve.
 
   ---
 
   - `redirectUrl`
   - `string`
 
-  The URL to redirect back to one the OAuth flow has completed successfully or unsuccessfully.
+  The full URL or path that the OAuth provider should redirect to on successful authorization on their part. Typically, this will be a simple `/sso-callback` route that calls [`Clerk.handleRedirectCallback`](/docs/references/javascript/clerk/handle-navigation#handle-redirect-callback) or mounts the [`<AuthenticateWithRedirectCallback />`](/docs/components/control/authenticate-with-callback) component. See the [custom flow](/docs/custom-flows/oauth-connections) for implementation details.
 
   ---
 

docs/references/javascript/session.mdx

@@ -160,7 +160,7 @@ function getToken(options?: GetTokenOptions): Promise<string | null>
   - `template?`
   - `string`
 
-  The name of the JWT template from the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates) to generate a new token from.<br />E.g. 'firebase', 'grafbase', or your custom template's name.
+  The name of the JWT template from the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=jwt-templates) to generate a new token from. E.g. 'firebase', 'grafbase', or your custom template's name.
 
   ---
 
@@ -174,7 +174,7 @@ function getToken(options?: GetTokenOptions): Promise<string | null>
   - `skipCache?`
   - `boolean`
 
-  Whether to skip the cache lookup and force a call to the server instead, even within the TTL. Useful if the token claims are time-sensitive or depend on data that can be updated (e.g. user fields).<br />Defaults to `false`.
+  Whether to skip the cache lookup and force a call to the server instead, even within the TTL. Useful if the token claims are time-sensitive or depend on data that can be updated (e.g. user fields). Defaults to `false`.
 
   ---
 

docs/references/javascript/sign-in/authenticate-with.mdx

@@ -23,30 +23,44 @@ function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promi
 
   The strategy to use for authentication. The following strategies are supported:
 
-  - `oauth_<provider>`: The user will be authenticated with their social sign-in account. [See available social providers](/docs/references/javascript/types/oauth#o-auth-provider).
-  - `saml`: The user will be authenticated with SAML. **Deprecated in favor of `enterprise_sso`.**
-  - `enterprise_sso`: The user will be authenticated either through SAML or OIDC, depending on the configuration of the [enterprise connection](/docs/authentication/enterprise-connections/overview) matching the identifier.
+  - `'oauth_<provider>'`: The user will be authenticated with their [social connection account](/docs/authentication/social-connections/overview). See a list of [supported values for `<provider>`](/docs/references/javascript/types/oauth#o-auth-provider).
+  - `'saml'` (deprecated): **Deprecated in favor of `'enterprise_sso'`.** The user will be authenticated with their [SAML account](/docs/authentication/enterprise-connections/overview#saml).
+  - `'enterprise_sso'`: The user will be authenticated either through SAML or OIDC depending on the configuration of their [enterprise SSO account](/docs/authentication/enterprise-connections/overview).
 
   ---
 
   - `redirectUrl`
   - `string`
 
-  The full URL or path to the route that will complete the OAuth or SAML flow. Typically, this will be a simple `/sso-callback` route that calls `Clerk.handleRedirectCallback` or mounts the `<AuthenticateWithRedirectCallback />` component.
+  The full URL or path that the OAuth provider should redirect to, on successful authorization on their part. Typically, this will be a simple `/sso-callback` route that calls [`Clerk.handleRedirectCallback`](/docs/references/javascript/clerk/handle-navigation#handle-redirect-callback) or mounts the [`<AuthenticateWithRedirectCallback />`](/docs/components/control/authenticate-with-callback) component. See the [custom flow](/docs/custom-flows/oauth-connections) for implementation details.
 
   ---
 
   - `redirectUrlComplete`
   - `string`
 
-  The URL that the user will be redirected to, after successful authorization from the OAuth provider and Clerk sign in.
+  The URL that the user will be redirected to once the sign-in is complete.
 
   ---
 
   - `identifier`
   - `string | undefined`
 
-  Identifier to use for targeting an enterprise connection at sign-in.
+    The ID used to target an enterprise connection during sign-in.
+
+  ---
+
+  - `emailAddress`
+  - `string | undefined`
+
+  The email address used to target an enterprise connection during sign-in.
+
+  ---
+
+  - `legalAccepted`
+  - `boolean | undefined`
+
+  A boolean indicating whether the user has agreed to the [legal compliance](/docs/authentication/configuration/legal-compliance) documents.
 </Properties>
 
 ### `authenticateWithMetamask()`