API-First JSDoc Cleanup Design

Date: 2026-03-03

Goal

Reduce the current lint warning set by documenting the actual library-facing API first, instead of mechanically adding JSDoc to every private helper.

Current State

Running:

./node_modules/.bin/eslint --resolve-plugins-relative-to ./node_modules --max-warnings 999 .

reports 37 warnings, all from JSDoc-related rules. The warnings are concentrated in:

  • lib/fake-xhr/index.js
  • lib/fake-server/index.js
  • lib/configure-logger/index.js
  • lib/event/*.js
  • lib/fake-server/fake-server-with-clock.js
  • lib/fake-server/log.js

Most warnings are jsdoc/require-jsdoc. A smaller number are shape-quality warnings such as jsdoc/reject-function-type and a missing @param.

Desired Policy

The primary documentation target is the public/exported API surface:

  • CommonJS exports
  • exported constructors
  • exported prototype methods that make up the library API

Private helpers should only receive JSDoc when one of these is true:

  • the helper is complex enough that the comment materially improves comprehension
  • lint requires it and there is no cleaner way to avoid low-value comment churn
  • the helper’s contract is subtle enough that documenting inputs/outputs reduces maintenance risk

Trivial local helpers should not be documented just to satisfy a documentation aesthetic. If the current lint configuration effectively requires that, the cleanup should expose the gap instead of pretending the policy is already aligned.

Approach 1: API-first cleanup with minimal internal coverage

Document exported constructors, exported factories, and public prototype methods with proper JSDoc. For remaining warnings, add short, accurate internal JSDoc only where the function is non-trivial or lint leaves no better option.

Pros

  • aligns with the desired documentation style
  • improves generated/consumer-facing docs where they matter
  • avoids turning internal files into comment-heavy noise

Cons

  • may not reach zero warnings if lint is stricter than the desired policy

Approach 2: Full warning burn-down

Add JSDoc everywhere ESLint asks for it.

Pros

  • quickest route to a fully green lint run

Cons

  • high comment noise
  • low-value docs on private helpers
  • makes future maintenance worse if comments become boilerplate

Approach 3: API-first cleanup plus lint policy adjustment

Document the public API properly, then adjust JSDoc lint rules so private helpers are no longer required to have comments.

Pros

  • best long-term alignment between policy and desired code style
  • removes incentive for comment spam

Cons

  • changes repo-wide lint policy
  • requires more care and team consensus than a pure code cleanup

Recommendation

Start with Approach 1. It is the lowest-risk path and should remove a meaningful portion of the warnings while improving the docs that users of the library are most likely to need.

After the API-first pass:

  • if lint is green, stop
  • if only a small number of useful internal docs remain, add them
  • if the remaining warnings are overwhelmingly trivial private helpers, propose a follow-up lint policy change rather than adding boilerplate comments

Scope Notes

  • Treat CommonJS exports and exported constructor/prototype APIs as public.
  • Prefer concrete parameter and return types over generic Function.
  • Fix malformed existing JSDoc when touched.
  • Do not rewrite modules just to manufacture better doc locations unless the existing structure makes the public API impossible to document cleanly.

Verification

Primary check:

./node_modules/.bin/eslint --resolve-plugins-relative-to ./node_modules --max-warnings 999 .

Success criteria:

  • warning count decreases materially
  • public/exported APIs have clear JSDoc
  • remaining warnings, if any, are mostly private-helper noise and can be evaluated for a lint-policy follow-up