Top Related Projects
:book: documentation for modern JavaScript
Documentation generator for TypeScript projects.
RESTful web API Documentation Generator.
🃏 A magical documentation site generator.
Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
Quick Overview
JSDoc is an API documentation generator for JavaScript. It uses specially formatted comments within JavaScript code to generate detailed documentation in HTML format. JSDoc helps developers create and maintain comprehensive documentation for their JavaScript projects.
Pros
- Easy to use with existing JavaScript code
- Generates well-structured HTML documentation
- Supports various tags for describing different aspects of code
- Integrates well with many IDEs and text editors for inline documentation
Cons
- Learning curve for mastering all available tags and syntax
- Can be verbose, potentially cluttering code with long comments
- May require manual updates to keep documentation in sync with code changes
- Limited customization options for output format compared to some alternatives
Code Examples
- Basic function documentation:
/**
* Calculates the sum of two numbers.
* @param {number} a - The first number.
* @param {number} b - The second number.
* @returns {number} The sum of a and b.
*/
function add(a, b) {
return a + b;
}
- Documenting a class:
/**
* Represents a book.
* @class
*/
class Book {
/**
* Create a book.
* @param {string} title - The title of the book.
* @param {string} author - The author of the book.
*/
constructor(title, author) {
this.title = title;
this.author = author;
}
/**
* Get the book's description.
* @returns {string} The book's title and author.
*/
getDescription() {
return `${this.title} by ${this.author}`;
}
}
- Documenting a module:
/**
* A module for handling user authentication.
* @module auth
*/
/**
* Authenticates a user.
* @param {string} username - The user's username.
* @param {string} password - The user's password.
* @returns {Promise<boolean>} A promise that resolves to true if authentication is successful.
*/
export async function authenticate(username, password) {
// Authentication logic here
}
Getting Started
To use JSDoc in your project:
-
Install JSDoc globally:
npm install -g jsdoc
-
Add JSDoc comments to your JavaScript files.
-
Generate documentation:
jsdoc path/to/your/javascript/files
-
View the generated documentation in the
out
directory.
For more advanced configuration, create a jsdoc.json
file in your project root to customize the documentation generation process.
Competitor Comparisons
:book: documentation for modern JavaScript
Pros of documentation
- Modern JavaScript support, including ES6+ syntax and Flow types
- Flexible output formats (HTML, JSON, Markdown) for various documentation needs
- Active development and community support
Cons of documentation
- Less widespread adoption compared to JSDoc
- May require additional configuration for complex projects
- Limited support for some legacy JavaScript patterns
Code Comparison
JSDoc example:
/**
* Calculates the sum of two numbers.
* @param {number} a - The first number.
* @param {number} b - The second number.
* @returns {number} The sum of a and b.
*/
function add(a, b) {
return a + b;
}
documentation example:
/**
* Calculates the sum of two numbers.
* @param {number} a The first number.
* @param {number} b The second number.
* @returns {number} The sum of a and b.
*/
function add(a: number, b: number): number {
return a + b;
}
Both JSDoc and documentation provide similar functionality for documenting JavaScript code. JSDoc has been the industry standard for a long time and offers extensive customization options. documentation, on the other hand, focuses on modern JavaScript features and provides a more streamlined experience. The choice between the two depends on project requirements, team preferences, and the specific JavaScript ecosystem being used.
Documentation generator for TypeScript projects.
Pros of TypeDoc
- Native support for TypeScript, providing better type inference and documentation
- Generates more modern and visually appealing documentation
- Offers themes and customization options for output
Cons of TypeDoc
- Limited support for JavaScript projects without TypeScript
- Steeper learning curve for developers unfamiliar with TypeScript
- Fewer plugins and extensions compared to JSDoc
Code Comparison
TypeDoc example:
/**
* Calculates the sum of two numbers.
* @param a The first number.
* @param b The second number.
* @returns The sum of a and b.
*/
function add(a: number, b: number): number {
return a + b;
}
JSDoc example:
/**
* Calculates the sum of two numbers.
* @param {number} a The first number.
* @param {number} b The second number.
* @returns {number} The sum of a and b.
*/
function add(a, b) {
return a + b;
}
TypeDoc is better suited for TypeScript projects, offering native support and improved type inference. It generates modern documentation with customizable themes. However, it has a steeper learning curve and limited JavaScript support. JSDoc, on the other hand, is more versatile for JavaScript projects and has a larger ecosystem of plugins, but lacks native TypeScript support and produces less visually appealing output.
RESTful web API Documentation Generator.
Pros of apidoc
- Supports multiple programming languages, not just JavaScript
- Generates a user-friendly, interactive HTML documentation
- Easier to maintain for REST API documentation
Cons of apidoc
- Requires specific comment syntax, which may not be as natural as JSDoc
- Less flexible for documenting complex JavaScript objects and classes
- Smaller community and ecosystem compared to JSDoc
Code Comparison
apidoc example:
/**
* @api {get} /user/:id Request User information
* @apiName GetUser
* @apiGroup User
*
* @apiParam {Number} id Users unique ID.
*/
JSDoc example:
/**
* Represents a user.
* @constructor
* @param {number} id - The user's unique identifier.
* @param {string} name - The user's name.
*/
function User(id, name) {
this.id = id;
this.name = name;
}
Both apidoc and JSDoc serve different purposes. apidoc is more focused on API documentation, while JSDoc is better suited for documenting JavaScript code structure. Choose the tool that best fits your project's needs and documentation requirements.
🃏 A magical documentation site generator.
Pros of Docsify
- Lightweight and easy to set up with no build process required
- Supports live reloading and hot updates for faster development
- Offers a wide range of plugins and themes for customization
Cons of Docsify
- Limited support for complex documentation structures
- Lacks built-in API documentation generation capabilities
- May require additional configuration for advanced features
Code Comparison
JSDoc example:
/**
* Calculates the sum of two numbers.
* @param {number} a - The first number.
* @param {number} b - The second number.
* @returns {number} The sum of a and b.
*/
function add(a, b) {
return a + b;
}
Docsify example:
# My Documentation
## Add Function
Calculates the sum of two numbers.
```javascript
function add(a, b) {
return a + b;
}
Additional Notes
JSDoc is primarily focused on generating API documentation from JavaScript source code comments, while Docsify is a more general-purpose documentation site generator. JSDoc excels at creating detailed API references, whereas Docsify is better suited for creating user-friendly documentation websites with a focus on simplicity and ease of use.
Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
Pros of Swagger UI
- Interactive API documentation with a user-friendly interface
- Supports OpenAPI (formerly Swagger) specification, a widely adopted standard
- Allows users to test API endpoints directly from the documentation
Cons of Swagger UI
- Requires more setup and configuration compared to JSDoc
- Limited to API documentation, while JSDoc can document entire JavaScript codebases
- May be overkill for simple projects or internal documentation needs
Code Comparison
JSDoc example:
/**
* Calculates the sum of two numbers.
* @param {number} a - The first number.
* @param {number} b - The second number.
* @returns {number} The sum of a and b.
*/
function add(a, b) {
return a + b;
}
Swagger UI example (YAML):
/add:
get:
summary: Add two numbers
parameters:
- name: a
in: query
required: true
schema:
type: number
- name: b
in: query
required: true
schema:
type: number
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
result:
type: number
JSDoc is better suited for documenting JavaScript code and generating documentation from source code comments. Swagger UI excels in creating interactive API documentation and is particularly useful for RESTful APIs. The choice between the two depends on the specific needs of the project and the type of documentation required.
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
JSDoc
An API documentation generator for JavaScript.
Want to contribute to JSDoc? Please read CONTRIBUTING.md
.
Installation and Usage
JSDoc supports stable versions of Node.js 8.15.0 and later. You can install
JSDoc globally or in your project's node_modules
folder.
To install the latest version on npm globally (might require sudo
;
learn how to fix this):
npm install -g jsdoc
To install the latest version on npm locally and save it in your package's
package.json
file:
npm install --save-dev jsdoc
Note: By default, npm adds your package using the caret operator in front of
the version number (for example, ^3.6.3
). We recommend using the tilde
operator instead (for example, ~3.6.3
), which limits updates to the most
recent patch-level version. See
this Stack Overflow answer for
more information about the caret and tilde operators.
If you installed JSDoc locally, the JSDoc command-line tool is available in
./node_modules/.bin
. To generate documentation for the file
yourJavaScriptFile.js
:
./node_modules/.bin/jsdoc yourJavaScriptFile.js
If you installed JSDoc globally, run the jsdoc
command:
jsdoc yourJavaScriptFile.js
By default, the generated documentation is saved in a directory named out
. You
can use the --destination
(-d
) option to specify another directory.
Run jsdoc --help
for a complete list of command-line options.
Templates and tools
The JSDoc community has created templates and other tools to help you generate and customize your documentation. Here are a few of them:
Templates
- jaguarjs-jsdoc
- DocStrap (example)
- jsdoc3Template (example)
- minami
- docdash (example)
- tui-jsdoc-template (example)
- better-docs (example)
Build tools
Other tools
For more information
- Documentation is available at jsdoc.app.
- Contribute to the docs at jsdoc/jsdoc.github.io.
- Join JSDoc's Slack channel.
- Ask for help on the JSDoc Users mailing list.
- Post questions tagged
jsdoc
to Stack Overflow.
License
JSDoc is copyright (c) 2011-present Michael Mathews micmath@gmail.com and the contributors to JSDoc.
JSDoc is free software, licensed under the Apache License, Version 2.0. See the
LICENSE
file for more details.
Top Related Projects
:book: documentation for modern JavaScript
Documentation generator for TypeScript projects.
RESTful web API Documentation Generator.
🃏 A magical documentation site generator.
Swagger UI is a collection of HTML, JavaScript, and CSS assets that dynamically generate beautiful documentation from a Swagger-compliant API.
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot