My code reviewer kept asking for JSDoc — so I built a zero-dep CLI that catches it first

I kept running eslint and thinking my codebase was fine — then someone opened a PR and the first comment was “this function needs JSDoc.”

The problem: linters check your syntax. Nobody checks whether your exported API is actually documented. Those are two very different things.

So I built jsdocscan — a zero-dependency CLI that walks your JS/TS files and flags every exported function or class that is missing JSDoc, or has undocumented parameters.

What it catches

Errors — exported function or class with no /** … */ block at all:

✗ src/api.js:12 fetchUser  missing JSDoc
✗ src/utils.js:34 formatDate  missing JSDoc

Enter fullscreen mode Exit fullscreen mode

Warnings — JSDoc exists but a parameter has no @param tag:

! src/render.js:7 renderCard  undocumented params: opts

Enter fullscreen mode Exit fullscreen mode

Exit codes are 0 (all clean), 1 (issues found), 2 (usage error) — pipe-friendly.

How to use it

# scan a directory
npx jsdocscan src/

# Python version
pip install jsdocscan
jsdocscan src/

# skip @param checks — just verify JSDoc exists
npx jsdocscan --no-params src/

# machine-readable output
npx jsdocscan --json src/ | jq '.[].findings'

# summary line only
npx jsdocscan --quiet src/

# custom extensions
npx jsdocscan --ext .js,.ts src/

Enter fullscreen mode Exit fullscreen mode

What it skips (intentionally)

• Non-exported functions and internal helpers — these are implementation details
• Destructured params ({ a, b }) — too many valid @param opts patterns
• TypeScript type annotations on params — name: string is stripped, @param name is still required

Zero dependencies

No parsers, no AST, no require("typescript"). It uses a line-by-line scanner that:

1. Detects export function/const/class patterns via regexes
2. Walks backwards to find a preceding /** */ block
3. Compares @param names in the JSDoc against the actual parameter list

npx jsdocscan works with zero install time. pip install jsdocscan brings in nothing extra.

Links

• npm: npmjs.com/package/jsdocscan
• PyPI: pypi.org/project/jsdocscan
• GitHub (Node): jjdoor/jsdocscan
• GitHub (Python): jjdoor/jsdocscan-py

Both versions pass the same 38-test suite. Same exit codes, same output format.