Write Api Docs

Rules:

• Do not assume everything in src/lib is public.
• Do not document private helpers just because they are exported within src/lib.
• If a declaration is not reachable from a package export, it is internal unless the user explicitly asks otherwise.

What To Document

For public API, add JSDoc to:

• exported functions
• exported classes
• exported interfaces
• exported type aliases
• exported public constants when they are part of the API shape

For public interfaces:

• add a JSDoc block on the interface itself
• add a property-level JSDoc block for every property on the interface, even when the name seems obvious

For public object-shaped type aliases:

• prefer an interface when you are introducing a new public object shape
• if an existing public type alias cannot reasonably become an interface, document the object shape as thoroughly as the syntax allows

For overloads:

• document the public overload signatures or the exported declaration in a way that makes the callable surface clear to users

JSDoc Style For This Repo

Keep comments short, factual, and user-facing.

• Describe what the API does, not how the implementation works internally.
• Prefer one concise summary sentence, then short @param / @returns docs as needed.
• Do not put TypeScript types in JSDoc tags. ESLint forbids JSDoc type syntax here because the source of truth is the TypeScript signature.
• Keep parameter names in JSDoc exactly aligned with the function signature.
• Use @returns for non-void functions and include a real description.
• For @param, include descriptions and do not add a hyphen before the description.
• Specify @param default values in parenthesis at the end of the comment, do not use @default tags
• Include an @example code block when it helps to show a use-case or pattern. Skip @example for simple getters, trivial constructors, or APIs whose usage is self-evident.
• Use {@link API} to link to related Remix APIs when it adds value. Don't link every related API — use discretion to avoid noise.
• Use backticks for all other unlinked code references — identifiers, HTTP methods, special values.

Good:

/**
 * Creates an {@link AuthProvider} for direct credentials-based authentication.
 *
 * @param options Parsing and verification hooks for submitted credentials.
 * @returns A provider that can be passed to `createAuthLoginRequestHandler()`.
 */
export function createCredentialsAuthProvider(...) {}

Avoid:

/**
 * @param {CredentialsAuthProviderOptions} options - options
 * @returns {CredentialsAuthProvider}
 */

ESLint Expectations

The relevant rules live in eslint.config.js.

For packages/**/*.{ts,tsx} (excluding tests), ESLint enforces JSDoc on callable declarations such as:

• function declarations
• function expressions
• arrow functions
• class declarations
• public methods

Important enforced details:

• jsdoc/require-param
• jsdoc/require-param-name
• jsdoc/require-param-description
• jsdoc/require-returns
• jsdoc/require-returns-description
• jsdoc/no-types
• jsdoc/check-param-names
• jsdoc/check-types
• jsdoc/check-alignment

Practical implication:

• if a public function takes parameters, document all of them
• if a public function returns a value, document the return value
• do not use JSDoc type annotations
• keep the block formatted cleanly enough to satisfy alignment checks

Review Checklist

• Did you start from package.json exports instead of guessing from src/lib?
• Are all documented declarations actually reachable from a public src/*.ts entry file?
• Do all public functions and methods have JSDoc with @param and @returns where required?
• Do public interfaces and type aliases have a concise doc block explaining what they represent?
• Does every property on every public interface have its own property-level JSDoc block?
• Did you avoid documenting internal helpers that are not exported publicly?
• Did pnpm run lint pass?