API-First JSDoc Cleanup Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Reduce the repo’s JSDoc lint warnings by documenting exported/CommonJS/public APIs first, while avoiding low-value comment spam on trivial private helpers.

Architecture: Use ESLint as the source of truth for the current warning set, group warnings by module and API surface, then add proper JSDoc to exported constructors, factories, and prototype methods. Re-run lint after each module group and only document private helpers when they are non-trivial or necessary to reach a sensible stopping point.

Tech Stack: Node.js, ESLint, JSDoc, CommonJS modules

Task 1: Establish the warning baseline and public API inventory

Files: - Review: lib/fake-xhr/index.js - Review: lib/fake-server/index.js - Review: lib/configure-logger/index.js - Review: lib/event/custom-event.js - Review: lib/event/event-target.js - Review: lib/event/event.js - Review: lib/event/progress-event.js - Review: lib/fake-server/fake-server-with-clock.js - Review: lib/fake-server/log.js

Step 1: Capture the current warning list

Run:

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

Expected: around 37 warnings, all JSDoc-related.

Step 2: Identify exported/public API targets

Build a short inventory of:

module.exports = ...
exported constructors
exported prototype methods intended for consumers

Expected: a prioritized list of API surfaces to document before touching private helpers.

Task 2: Document event and logger public APIs

Files: - Modify: lib/configure-logger/index.js - Modify: lib/event/custom-event.js - Modify: lib/event/event-target.js - Modify: lib/event/event.js - Modify: lib/event/progress-event.js

Step 1: Write the failing lint expectation

Run:

./node_modules/.bin/eslint --resolve-plugins-relative-to ./node_modules --max-warnings 999 lib/configure-logger/index.js lib/event/*.js

Expected: JSDoc warnings on exported/public constructors and functions.

Step 2: Add API-facing JSDoc

Document the exported/public pieces with concise but specific JSDoc, including:

purpose
params
return values where applicable
notable behavior only when it is not obvious from the name

Prefer concrete types over:

/**
 * @returns {Function|undefined}
 */

when a more specific callable shape can be expressed.

Step 3: Re-run targeted lint

Run:

./node_modules/.bin/eslint --resolve-plugins-relative-to ./node_modules --max-warnings 999 lib/configure-logger/index.js lib/event/*.js

Expected: warning count drops, with any remaining warnings limited to private helpers or intentionally deferred files.

Task 3: Document fake server public APIs

Files: - Modify: lib/fake-server/index.js - Modify: lib/fake-server/fake-server-with-clock.js - Modify: lib/fake-server/log.js

Step 1: Run targeted lint for fake server files

Run:

./node_modules/.bin/eslint --resolve-plugins-relative-to ./node_modules --max-warnings 999 lib/fake-server/*.js

Expected: warnings concentrated on exported constructors/factories and a few private helpers.

Step 2: Add JSDoc to exported/public APIs

Document:

exported server factory/constructor entry points
public methods exposed through the fake server API
any exported log helper whose contract is consumer-visible

Use minimal internal JSDoc only where the helper contract is subtle or lint still requires it.

Step 3: Re-run targeted lint

Run:

./node_modules/.bin/eslint --resolve-plugins-relative-to ./node_modules --max-warnings 999 lib/fake-server/*.js

Expected: warning count drops again without broad private-helper comment churn.

Task 4: Document fake XHR public APIs and fix malformed JSDoc

Files: - Modify: lib/fake-xhr/index.js

Step 1: Run targeted lint for fake XHR

Run:

./node_modules/.bin/eslint --resolve-plugins-relative-to ./node_modules --max-warnings 999 lib/fake-xhr/index.js

Expected: the largest remaining warning cluster.

Step 2: Add JSDoc to exported/public API surface

Document the public/exported parts of fake XHR first:

exported constructor/factory surface
public static members where useful
public prototype methods intended for users of the library

Also fix any malformed existing JSDoc such as missing @param declarations.

Step 3: Add minimal internal JSDoc only where justified

Only document private helpers when one of these is true:

the helper is complex or contract-heavy
lint still warns and the comment can stay short and meaningful

Skip trivial helpers if they can remain undocumented without undermining the lint goal.

Step 4: Re-run targeted lint

Run:

./node_modules/.bin/eslint --resolve-plugins-relative-to ./node_modules --max-warnings 999 lib/fake-xhr/index.js

Expected: warning count falls materially; remaining warnings should be easy to classify as either justified internal docs or policy mismatch.

Task 5: Decide stop point or policy follow-up

Files: - Modify: docs/plans/2026-03-03-api-first-jsdoc-cleanup-design.md (optional notes only)

Step 1: Run full lint

Run:

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

Expected: significantly fewer warnings than the starting 37.

Step 2: Classify any remaining warnings

Separate the remainder into:

meaningful missing docs on public API
useful internal docs worth adding
low-value private-helper warnings caused by current lint policy

Step 3: Choose completion rule

If the remaining warnings are low-value private-helper noise, stop the code cleanup and prepare a follow-up lint-policy proposal instead of adding boilerplate comments.

If the remainder is still meaningful API documentation debt, continue with one more small cleanup pass.

Task 6: Final verification and commit

Files: - Modify: the touched source files only

Step 1: Run lint with repo threshold

Run:

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

Expected: PASS if the warning count reaches the current budget, or a clearly smaller failure set than the starting point if policy mismatch remains.

Step 2: Run tests

Run:

npm test

Expected: PASS

Step 3: Commit

git add lib/configure-logger/index.js lib/event/*.js lib/fake-server/*.js lib/fake-xhr/index.js docs/plans/2026-03-03-api-first-jsdoc-cleanup-design.md docs/plans/2026-03-03-api-first-jsdoc-cleanup.md
git commit -m "docs: improve public api jsdoc coverage"