JSDoc — API Documentation Generator for JavaScript

Introduction

JSDoc is the de facto standard for documenting JavaScript APIs. It reads specially formatted comments in source code and generates a complete HTML documentation website. Beyond documentation, JSDoc annotations are used by editors like VS Code for IntelliSense and by TypeScript for type checking via JSDoc-powered type annotations.

What JSDoc Does

• Parses /** ... */ comment blocks with @param, @returns, @typedef, and dozens of other tags
• Generates a browsable HTML documentation site with navigation, search, and source links
• Supports custom templates and plugins for controlling output format and content
• Integrates with TypeScript's type checker to provide type information without .ts files
• Handles ES modules, classes, async functions, and modern JavaScript syntax

Architecture Overview

JSDoc runs as a Node.js CLI that processes source files in three phases: parsing, template rendering, and output. The parser uses a combination of regular expressions and an AST (via Babylon/Acorn) to extract doclet metadata from comment blocks. Doclets are normalized into a standard schema and passed to a template engine. The default template uses Underscore.js templates, but the jsdoc-template plugin interface allows full replacement. Plugins hook into events like parseBegin, newDoclet, and processingComplete.

Self-Hosting & Configuration

• Create a jsdoc.json or .jsdoc.conf.json config file to set source paths and output directory
• Specify included/excluded file patterns in the source configuration section
• Install custom templates via npm and reference them in the opts.template config field
• Add plugins like jsdoc-plugin-markdown for markdown rendering in descriptions
• Integrate into CI by running jsdoc -c jsdoc.json as a build step

Key Features

• Comprehensive tag set covering parameters, return values, types, examples, deprecated notices, and more
• TypeScript integration where @type, @param, and @returns annotations are recognized by tsc
• Pluggable template system for custom documentation themes
• Markdown support in description text
• Tutorial and external documentation linking via @tutorial and @link tags

Comparison with Similar Tools

• TypeDoc — generates docs from TypeScript source and type information; JSDoc works with plain JavaScript and comment annotations
• Docusaurus — a documentation site generator for prose docs; JSDoc generates API reference from source code
• ESDoc — an alternative JS doc generator with coverage reporting; JSDoc has broader ecosystem support and editor integration
• TSDoc — a specification for TypeScript doc comments; JSDoc is both a specification and a generator tool

FAQ

Q: Can JSDoc document TypeScript files? A: JSDoc is designed for JavaScript. For TypeScript, use TypeDoc instead, or use JSDoc annotations in .js files for TypeScript type checking.

Q: How do I use a custom theme? A: Install a template package (e.g., better-docs, docdash) and set opts.template in your config file.

Q: Does JSDoc support ES module syntax? A: Yes, JSDoc handles import/export statements and documents exported members.

Q: Can I generate markdown instead of HTML? A: Use community plugins like jsdoc-to-markdown to output markdown files instead of HTML.

Sources

• https://github.com/jsdoc/jsdoc
• https://jsdoc.app