diff --git a/.changeset/chatty-dolls-work.md b/.changeset/chatty-dolls-work.md new file mode 100644 index 00000000000..4a140e29001 --- /dev/null +++ b/.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 diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index dabfd875c5d..a12d1a48c6a 100644 --- a/docs/CONTRIBUTING.md +++ b/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; + /** + * Optional parameter with a default value. + * @default false + */ + isOffline?: boolean; +}; + +type FnReturn = Array; + +/** + * 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. diff --git a/packages/backend/src/tokens/types.ts b/packages/backend/src/tokens/types.ts index 3fb22480e39..12da5acdeff 100644 --- a/packages/backend/src/tokens/types.ts +++ b/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 [``](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 [``](https://clerk.com/docs/components/organization/organization-switcher). * * @example * ["/orgs/:slug", "/orgs/:slug/(.*)"] diff --git a/packages/clerk-js/src/core/errors.ts b/packages/clerk-js/src/core/errors.ts index 33609f0287e..3a589781565 100644 --- a/packages/clerk-js/src/core/errors.ts +++ b/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.`); diff --git a/packages/elements/src/internals/machines/form/form.context.ts b/packages/elements/src/internals/machines/form/form.context.ts index 6a8781bd463..43948935e66 100644 --- a/packages/elements/src/internals/machines/form/form.context.ts +++ b/packages/elements/src/internals/machines/form/form.context.ts @@ -34,9 +34,9 @@ type MapValue = A extends Map ? 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) => diff --git a/packages/elements/src/react/sign-in/action/resend.tsx b/packages/elements/src/react/sign-in/action/resend.tsx index 251d58f3908..2e186168de3 100644 --- a/packages/elements/src/react/sign-in/action/resend.tsx +++ b/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 . * - * @note This component is not intended to be used directly. Instead, use the component. + * > [!NOTE] + * > This component is not intended to be used directly. Instead, use the `` component. * * @example + * ```tsx * import { Action } from '@clerk/elements/sign-in'; *

Resendable in: {resendableAfter}s

}>Resend; + * ``` */ export const SignInResend = React.forwardRef( ({ asChild, fallback, ...rest }, forwardedRef) => { diff --git a/packages/elements/src/react/sign-up/action/resend.tsx b/packages/elements/src/react/sign-up/action/resend.tsx index 7eb7f775d11..4d75fe04db9 100644 --- a/packages/elements/src/react/sign-up/action/resend.tsx +++ b/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 . * - * @note This component is not intended to be used directly. Instead, use the component. + * > [!NOTE] + * > This component is not intended to be used directly. Instead, use the `` component. * * @example + * ```tsx * import { Action } from '@clerk/elements/sign-in'; *

Resendable in: {resendableAfter}s

}>Resend; + * ``` */ export const SignUpResend = React.forwardRef( ({ asChild, fallback, ...rest }, forwardedRef) => { diff --git a/packages/nextjs/src/app-router/server/auth.ts b/packages/nextjs/src/app-router/server/auth.ts index a6a4c39a632..019b7e23fd3 100644 --- a/packages/nextjs/src/app-router/server/auth.ts +++ b/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>; @@ -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>; }; @@ -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). */ diff --git a/packages/nextjs/src/server/createGetAuth.ts b/packages/nextjs/src/server/createGetAuth.ts index 86c3f83b8e0..56edce21415 100644 --- a/packages/nextjs/src/server/createGetAuth.ts +++ b/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. diff --git a/packages/shared/src/error.ts b/packages/shared/src/error.ts index e908e1ddf78..ef87aa4b259 100644 --- a/packages/shared/src/error.ts +++ b/packages/shared/src/error.ts @@ -164,7 +164,6 @@ export class ClerkRuntimeError extends Error { * The error message. * * @type {string} - * @memberof ClerkRuntimeError */ message: string; @@ -172,7 +171,6 @@ export class ClerkRuntimeError extends Error { * 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}`; diff --git a/typedoc.config.mjs b/typedoc.config.mjs index 53778f7a5e2..cbe273970ad 100644 --- a/typedoc.config.mjs +++ b/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',