# JSDoc — API Documentation Generator for JavaScript

> The standard documentation generator for JavaScript projects. Parses structured comment annotations in source code to produce searchable HTML API docs with type information, parameter descriptions, and cross-references.

## Install

Save in your project root:

# JSDoc — API Documentation Generator for JavaScript

## Quick Use
```bash
npm install -g jsdoc
jsdoc src/ -d docs/
# Open docs/index.html in a browser
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-dff9be7c
Author: AI Open Source