Convert Figma logo to code with AI

jsdoc logojsdoc

An API documentation generator for JavaScript.

15,117
1,454
15,117
443

Top Related Projects

:book: documentation for modern JavaScript

7,883

Documentation generator for TypeScript projects.

9,720

RESTful web API Documentation Generator.

28,596

🃏 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

  1. 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;
}
  1. 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}`;
    }
}
  1. 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:

  1. Install JSDoc globally:

    npm install -g jsdoc
    
  2. Add JSDoc comments to your JavaScript files.

  3. Generate documentation:

    jsdoc path/to/your/javascript/files
    
  4. 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.

7,883

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.

9,720

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.

28,596

🃏 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 Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

JSDoc

Build status

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

Build tools

Other tools

For more information

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.

NPM DownloadsLast 30 Days