DEV Community

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

Posted on

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

#showdev #javascript #cli #opensource

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

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

Top comments (2)

Collapse
 
frank_signorini profile image
Frank •

How does your CLI handle complex JSDoc cases like nested callbacks or promises, and are there plans to integrate it with existing linting tools like eslint?

Collapse
 
frank_signorini profile image
Frank •

How does your CLI handle complex JSDoc scenarios, such as documenting nested functions or async/await syntax?