jsdoc

name

jsdoc

description

Use this skill for adding, improving, standardizing, or reviewing JSDoc comments in JavaScript and TypeScript codebases. Trigger this skill when documenting functions, arrow functions, exported APIs, hooks, React components, classes, utility modules, parser/evaluator logic, domain helpers, and public contracts. Use it when the task requires professional documentation quality, consistent JSDoc structure, and accurate docs that match real implementation.

Purpose

This skill provides a practical JSDoc playbook for Codex.

Use it when the task involves:

• adding missing JSDoc
• improving low-quality JSDoc
• standardizing documentation style
• documenting public APIs
• documenting non-trivial internal helpers
• documenting React hooks/components
• documenting engine/parser/evaluator logic
• documenting TypeScript-heavy code without weakening type clarity

The goal is to produce professional, accurate, readable JSDoc that helps maintainers understand intent, contracts, and important behavior.

This skill is not for adding noisy boilerplate to every trivial line of code.

When to use this skill

Use this skill when the task includes any of the following:

• add JSDoc to exported functions or modules
• rewrite weak or vague comments into professional JSDoc
• standardize JSDoc formatting across a module or directory
• document parser/evaluator/engine code
• document React components, hooks, reducers, context helpers, utilities
• document function contracts, invariants, edge cases, and return semantics
• improve code readability for future maintainers
• refactor JSDoc so it matches current implementation

Do not use this skill when:

• the task is pure implementation with no meaningful documentation need
• the code is trivial and comments would only repeat the obvious
• inline comments are more appropriate than block-level JSDoc
• the repository explicitly does not want JSDoc for the target files

Core principles

1. Document intent, not syntax.

• JSDoc should explain purpose, contract, invariants, edge cases, and behavior.
• Do not mechanically restate obvious code.

2. Keep docs accurate.

• JSDoc must match the real implementation.
• Never document behavior that is not actually implemented.

3. Prefer high-signal documentation.

• Exported APIs and non-trivial internal helpers deserve stronger documentation.
• Tiny obvious helpers should not receive verbose boilerplate unless consistency clearly requires it.

4. Write for maintainers.

• The audience is the future engineer reading the code.
• Explain why a function exists when that matters.

5. Preserve behavior.

• JSDoc work must not change runtime behavior unless the task explicitly includes refactoring.

6. Respect TypeScript.

• JSDoc complements TypeScript.
• Do not duplicate every obvious type detail if the signature already says it clearly.
• Focus on semantics, expectations, and caveats.

What to document

Highest priority

Document these first:

• exported functions
• exported classes
• exported constants with function behavior
• public hook APIs
• public React components
• context accessor hooks
• reducer entry points
• parser/evaluator entry points
• conversion/normalization helpers
• non-trivial utilities with reusable contracts

Medium priority

Document when useful:

• internal helpers with non-obvious behavior
• functions with important assumptions
• functions with edge-case behavior
• functions with subtle return semantics
• functions that manipulate parser/evaluator state
• helpers with invariants or ordering requirements

Low priority

Usually avoid heavy JSDoc for:

• tiny obvious wrappers
• simple one-line transforms with obvious names
• internal constants with self-explanatory meaning
• code where JSDoc would only duplicate the signature

Standard JSDoc structure

Use concise, professional JSDoc.

Typical shape:

/**
 * Short summary sentence.
 *
 * Optional longer explanation when useful.
 *
 * @param input Description of the parameter semantics.
 * @param options Description of optional behavior or constraints.
 * @returns Description of the returned value and important semantics.
 */

Use only the tags that add value.

Common useful tags:

• @param
• @returns
• @throws
• @example
• @remarks if the repo uses it
• @template for generics only when clarification is useful

Avoid tag spam.

Function documentation rules

Document:

• what the function does
• what the inputs mean semantically
• what the return value means
• notable invariants
• edge-case handling where important
• whether the function is deterministic/pure when relevant

Avoid:

• repeating the function name in different words with no added value
• narrating implementation steps unless they matter to the contract
• documenting obvious parameter types already visible in TypeScript

Example:

/**
 * Resolves a variable name against row, table-local, and outer note scopes.
 *
 * Row-scoped values take precedence over table-local declarations, which in turn
 * take precedence over outer note variables.
 *
 * @param name The identifier being resolved.
 * @param context The layered resolution context for the current evaluation pass.
 * @returns The resolved value when found, otherwise `null`.
 */
const resolveScopedValue = (name: string, context: ResolutionContext): Value | null => {
  // ...
};

Arrow function documentation rules

When functions are implemented as:

const evaluateExpression = (...) => { ... };

place JSDoc immediately above the const.

Example:

/**
 * Evaluates a parsed expression node into a deterministic runtime value.
 *
 * @param node The AST node to evaluate.
 * @param context The current evaluation context.
 * @returns The evaluated runtime value.
 */
const evaluateExpression = (...) => {
  // ...
};

React component documentation rules

Document React components when:

• they are exported
• they are reusable/shared
• their props contract is non-trivial
• their render semantics are not obvious

Focus on:

• responsibility
• key UI contract
• notable props semantics
• controlled/uncontrolled behavior if relevant

Example:

/**
 * Renders a compact billing summary with subtotal, tax, and total values.
 *
 * The component is presentational and does not own billing state.
 *
 * @param props Component props.
 * @returns The rendered billing summary panel.
 */
const BillingSummary = ({ subtotal, tax, total }: BillingSummaryProps) => {
  // ...
};

Do not over-document every tiny local presentational component unless the repository convention strongly prefers it.

Hook documentation rules

Hooks deserve strong JSDoc when exported or reused.

Document:

• what the hook manages
• what it returns
• important lifecycle/behavior expectations
• whether it throws when provider/context is missing
• async semantics if relevant

Example:

/**
 * Provides access to the active document context.
 *
 * @returns The active document context value.
 * @throws {Error} Thrown when used outside the corresponding provider.
 */
const useDocumentContext = (): DocumentContextValue => {
  // ...
};

Class documentation rules

If the repository contains classes, document:

• responsibility
• lifecycle role
• important invariants
• constructor semantics
• public methods only as needed

Avoid documenting trivial getters/setters with obvious names unless behavior is non-obvious.

Type and interface documentation rules

Use JSDoc on interfaces/types when:

• the type is public
• the type represents an important domain concept
• the meaning is not obvious from field names alone

Example:

/**
 * Represents a table-local declaration available during table row evaluation.
 */
interface TableLocalVariableNode {
  name: string;
  expression: ExpressionNode;
  sourceRange: SourceRange;
}

Do not add bloated comments to every trivial property unless necessary.

Module-level documentation rules

Add top-of-file JSDoc when a file/module has:

• an important role in architecture
• parser/evaluator responsibilities
• a non-obvious public purpose

Good candidates:

• parser entry module
• evaluator entry module
• resolver module
• normalization/conversion module
• React provider module
• feature-level hook module

@param guidance

A @param description should explain semantics, not restate the variable name.

Weak:

@param value The value.

Better:

@param value The normalized currency amount to format for display.

@returns guidance

A @returns description should explain what is returned and any important contract semantics.

Weak:

@returns A boolean.

Better:

@returns `true` when the compared units are compatible and can be normalized into the same unit family.

@throws guidance

Use @throws when the function intentionally throws and that matters to callers.

Example:

/**
 * @throws {Error} Thrown when the hook is used outside its provider.
 */

Do not invent @throws if the function does not intentionally expose throwing behavior.

@example guidance

Use @example when:

• syntax is easier to understand with a small example
• the function has tricky usage
• the repository documentation style benefits from executable-looking examples

Keep examples short and realistic.

Example:

/**
 * Formats a money value for compact display.
 *
 * @param amount The normalized money amount.
 * @param currency The ISO currency code to render.
 * @returns A compact localized money string.
 * @example
 * formatMoney(12.5, 'USD');
 * // "$12.50"
 */

TypeScript-specific guidance

Prefer semantic docs over type duplication

If TypeScript already expresses the exact type clearly, use JSDoc to explain:

• meaning
• invariants
• ordering
• constraints
• edge cases
• failure modes

Generics

Use @template only when it adds clarity.

Example:

/**
 * Returns the first item matching the supplied predicate.
 *
 * @template T
 * @param items The collection to scan.
 * @param predicate The predicate used to select an item.
 * @returns The first matching item, or `null` when none match.
 */

Overloads

If overloaded behavior exists, ensure JSDoc reflects the real semantic differences. Do not describe only one overload when multiple materially different call shapes exist.

JSDoc quality bar

Good JSDoc should be:

• accurate
• concise
• specific
• implementation-aware
• maintainable
• useful during refactoring

Bad JSDoc is:

• vague
• redundant
• stale
• copy-pasted
• disconnected from real code behavior

Editing strategy for Codex

When using this skill, Codex should:

1. inspect the real implementation first
2. identify exported and non-trivial internal APIs
3. document high-value surfaces first
4. avoid commenting every trivial helper by default
5. preserve runtime behavior
6. improve weak comments rather than piling new noise on top
7. keep tone and formatting consistent across the edited files

Review checklist

When reviewing JSDoc, check:

• does it match the real behavior?
• does it explain intent or just restate code?
• are @param descriptions semantic?
• are @returns descriptions meaningful?
• are @throws tags real and justified?
• is the documentation level appropriate for the function’s importance?
• are exported APIs documented first?
• is the style consistent across the file/module?

Output expectations for Codex

When this skill is selected, Codex should produce JSDoc that:

• is professionally written
• matches real implementation
• uses appropriate tags only
• complements TypeScript instead of duplicating it mechanically
• prioritizes exported and non-trivial logic
• avoids boilerplate spam

Skill resources

Use these companion files when relevant:

• react-jsdoc-patterns.md

  • use when documenting React components, hooks, providers, reducers, and UI utilities

• engine-jsdoc-patterns.md

  • use when documenting parser, evaluator, resolver, formatter, diagnostics, and other deterministic engine code

• jsdoc-anti-patterns.md

  • use when reviewing or refactoring noisy, vague, stale, or low-value JSDoc