# JSDoc: generating API documentation from JavaScript comments

> JSDoc turns annotations written directly above your functions into a browsable HTML API reference. It is a documentation generator first, and a type-checking aid only when you pair it with a checker.

**jsdoc/jsdoc** — Project brief: An API documentation generator for JavaScript. Run jsdoc help for a complete list of command-line options.

- Repository: https://github.com/jsdoc/jsdoc
- Website: https://jsdoc.app/
- Stars: 15,469 · Forks: 1,494
- Language: JavaScript
- License: Apache-2.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/jsdoc-jsdoc

## What JSDoc solves for JavaScript projects without a build step

JavaScript has no compiler-enforced contract. A function signature is whatever the author wrote that week, and the only place the intent survives is the comment above it. JSDoc takes those comments and turns them into a static HTML site: one page per documented symbol, cross-linked, with the parameter names, types and descriptions you wrote in the source.

The audience is narrow and specific. It is a library author who ships JavaScript to other people and wants a reference page without adopting a type system. It is a team maintaining a large legacy codebase where rewriting into TypeScript is not on the table. It is also anyone who wants annotations that live in the same file as the code, so that reading the source and reading the docs are the same act.

The README describes the project in one line: "An API documentation generator for JavaScript." That framing matters. JSDoc does not check your types, does not fail a build on a mismatch, and does not ship a language server. It reads comments and writes files.

## How JSDoc reads comments and writes a documentation tree

The pipeline is source in, HTML out. You point the command-line tool at one or more JavaScript files. It parses each file, collects the comment blocks that carry JSDoc tags, resolves each tag into a documented symbol, and renders the result into a destination directory.

The README gives the default: "By default, the generated documentation is saved in a directory named out." That default is worth knowing before your first run, because it means a bare invocation drops a new top-level folder into your working directory. The --destination option, abbreviated -d, overrides it.

What the repository does not describe is the tag vocabulary itself. The README defers to jsdoc.app for documentation and tells you to run jsdoc --help for the option list. So the mechanism is visible, but the surface area of tags such as param, returns or typedef is documented elsewhere, not in the repository README. If you are evaluating JSDoc from the repository alone, you will see how to invoke it and not what to write inside the comments.

## Installing JSDoc and generating your first page

The README supports two installation shapes. Installing globally puts a jsdoc command on your PATH. Installing locally places the binary in ./node_modules/.bin, which is the safer choice because it pins the version to your project.

The README's global install command is:

```bash
npm install -g jsdoc
```

The README notes this might require sudo, and links to npm's documentation on resolving EACCES permission errors if it does. If you would rather avoid that entirely, install locally instead and save the dependency:

```bash
npm install --save-dev jsdoc
```

The README explicitly recommends the tilde operator over npm's default caret. Where npm would write ^3.6.3, the README suggests ~3.6.3, which restricts updates to patch releases. That advice is aimed at the 3.x line, so check what your install actually writes into package.json rather than assuming.

With a local install, the README says the tool is available in ./node_modules/.bin. To document a single file:

```bash
./node_modules/.bin/jsdoc yourJavaScriptFile.js
```

After the command finishes, the README says the output lands in a directory named out. Open the HTML file inside it to see the generated reference. If you installed globally, the README's equivalent is simply jsdoc yourJavaScriptFile.js. To send the output somewhere else, use the --destination option, or -d for short, and run jsdoc --help for the full option list.

## Where JSDoc stops being the right tool

JSDoc generates documentation. It does not enforce anything. If a comment says a parameter is a number and the caller passes a string, JSDoc will happily render the comment and say nothing about the call site. Teams that expect the annotations to act as a type system will be disappointed, and the README makes no such promise.

The second limitation is version currency. The most recent release listed for the project is 4.0.4, dated 2024-10-19. The release before it, 3.5.5, is dated 2017-09-14. That is a seven-year gap between minor lines, and it means the 3.x documentation you find in blog posts and Stack Overflow answers may describe behaviour that changed in 4.x. The README itself still carries a note recommending the tilde operator with a 3.6.3 example, which suggests parts of the README have not been refreshed alongside the 4.x line.

The third limitation is scope of documentation. The repository README covers installation, invocation and a list of community templates and build tools. It does not document the tag set, the configuration file format, or how to write a custom template. All of that is delegated to jsdoc.app. If your evaluation process is "read the repository," you will come away knowing how to run the tool and not how to use it.

## JSDoc against TypeScript, and against jsdoc-to-markdown

The comparison people reach for is TypeScript, and the difference is structural rather than cosmetic. TypeScript adds a separate compilation step and a separate file format for type information. JSDoc keeps annotations inside the JavaScript comments, so the source file remains the single artifact and there is no build step required to produce documentation. The trade is that TypeScript validates at build time and JSDoc does not validate at all. A team that wants type errors surfaced in CI should not expect JSDoc to provide them.

A closer alternative in the same niche is jsdoc-to-markdown, which the README lists under "Other tools." Both consume the same comment annotations, but they emit different things: JSDoc produces a browsable HTML site, while jsdoc-to-markdown produces Markdown files. If your documentation lives in a wiki, a README or a static site generator that consumes Markdown, the Markdown output fits the publishing pipeline better. If you want a searchable, cross-linked API reference with per-symbol pages, JSDoc's HTML output is the thing you actually want.

The README also lists a set of alternative HTML templates, including jaguarjs-jsdoc, DocStrap, jsdoc3Template, minami, docdash, tui-jsdoc-template and better-docs. Those are presentation layers over the same generator, not different generators, so switching templates does not change what gets documented.

## Maintenance cost, engine requirements and the Apache-2.0 licence

The repository's package.json declares an engine range of ^22.13.0 || >=23.0.0 for Node.js. That is the development toolchain for the repository itself, and it is noticeably newer than the README's statement that "JSDoc supports stable versions of Node.js 8.15.0 and later." The two are not necessarily in conflict, since one describes building the project and the other describes running it, but the gap is wide enough that you should check which one applies to the package you install rather than assuming either.

On upgrades: the release history shows 4.0.4 as the most recent entry, with the prior line at 3.5.5 from 2017. A major-version jump with that much time behind it is the kind of upgrade where you read the changelog first. The repository has a CHANGES.md at its top level, which is where that record lives.

The project is licensed under Apache-2.0, and the README states that JSDoc is free software under that licence, with the LICENSE file holding the details. Apache-2.0 is a permissive licence that includes an explicit patent grant, which matters if you are embedding the tool in a commercial pipeline. This is a description of the licence text, not legal advice; if the distinction matters to your organisation, have counsel read the LICENSE file rather than a review.

## Conclusion

Adopt JSDoc if your codebase is plain JavaScript and you want a static HTML API reference built from comments you already maintain, or if you want type annotations that survive in the source rather than in a separate file. Skip it if you need a single tool that both checks types and emits documentation, because JSDoc only does the second job. Before committing, verify two things: that your Node.js version satisfies the engine range declared in the repository's package.json, and that the default output directory named out does not collide with anything you already publish from. Then run jsdoc --help and read the option list, because the README points there rather than documenting flags inline.

## FAQ

### What is JSDoc used for?

It generates API documentation for JavaScript. You annotate your source with JSDoc comments, run the command-line tool over your files, and it writes HTML into an output directory.

### Is JSDoc better than TypeScript?

They do different jobs. JSDoc reads comments and produces documentation, while TypeScript adds a compilation step that checks types. The README describes JSDoc only as an API documentation generator, so it is not a replacement for a type checker.

### How do I install JSDoc?

The README gives two commands: npm install -g jsdoc for a global install, or npm install --save-dev jsdoc to add it to your project's node_modules folder. The README recommends the tilde operator over npm's default caret in package.json.

### How do I use JSDoc?

Point the tool at a JavaScript file. With a local install, the README's example is ./node_modules/.bin/jsdoc yourJavaScriptFile.js; with a global install it is jsdoc yourJavaScriptFile.js. Output goes to a directory named out unless you pass --destination.

### What are the different types of types in JSDoc and how do they work?

The repository README does not document the tag or type vocabulary. It points to jsdoc.app for documentation and says to run jsdoc --help for the complete list of command-line options, so the type system is documented outside the repository.

### How do I link to another file in JSDoc?

The repository README does not cover linking syntax. It directs readers to jsdoc.app for documentation, and the tag reference that would define a link tag is not included in the repository itself.

## Sources

- [Official documentation](https://jsdoc.app/)
- [Official README](https://github.com/jsdoc/jsdoc#readme)
- [Project repository](https://github.com/jsdoc/jsdoc)
- [Release notes](https://github.com/jsdoc/jsdoc/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jsdoc-jsdoc