Write API Docs

Write API Docs

Overview

Use this skill when documenting public APIs in Remix packages.

The goal is to document the API users can actually import, not every helper in src/lib. Work from the package exports outward, add concise JSDoc to the public declarations, and make sure the result passes the repo's ESLint JSDoc rules.

This skill owns detailed JSDoc style and lint expectations. If documenting an API reveals that the TypeScript contract itself should change, use the typescript-expert skill for the type design work.

Workflow

1. Identify the package's public exports.
2. Find the src entry files that back those exports.
3. Trace those entry files to the declarations they re-export from src/lib.
4. Add or tighten JSDoc on the public declarations only.
5. Run package typecheck if appropriate and always run pnpm run lint.

How To Identify Public API

The source of truth is the package's package.json.

• Start with package.json exports.
• Each public export should map to a file directly under src/.
• Those src/*.ts entry files define the public surface by re-exporting symbols from src/lib.
• A declaration in src/lib is public only if it is re-exported by one of those public src/*.ts entry files.

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?