Introduction to JSDoc to Markdown

JSDoc to Markdown is a powerful tool that allows developers to generate markdown documentation from JSDoc comments in their JavaScript code. This process simplifies the creation of readable and comprehensive documentation, which can be hosted or shared easily.

Useful API Explanations with Code Snippets

Installation

  npm install -g jsdoc-to-markdown

Basic Usage

  /**
   * Adds two numbers.
   * @param {number} a - The first number.
   * @param {number} b - The second number.
   * @returns {number} The sum of the two numbers.
   */
  function add(a, b) {
    return a + b;
  }

  jsdoc2md index.js > API.md

Advanced Usage

  /**
   * Represents a Book.
   * @constructor
   * @param {string} title - The title of the book.
   * @param {string} author - The author of the book.
   */
  function Book(title, author) {
    this.title = title;
    this.author = author;
  }

  /**
   * Get the book title.
   * @returns {string} The title of the book.
   */
  Book.prototype.getTitle = function() {
    return this.title;
  };

  /**
   * Get the book author.
   * @returns {string} The author of the book.
   */
  Book.prototype.getAuthor = function() {
    return this.author;
  };

  jsdoc2md book.js > BookAPI.md

App Example using Documented APIs

  const express = require('express');
  const app = express();

  /**
   * @api {get} /add/:a/:b Add two numbers
   * @apiParam {Number} a The first number.
   * @apiParam {Number} b The second number.
   * @apiSuccess {Number} sum The sum of the two numbers.
   */
  app.get('/add/:a/:b', (req, res) => {
    const a = parseInt(req.params.a);
    const b = parseInt(req.params.b);
    res.json({ sum: add(a, b) });
  });

  /**
   * @api {get} /book Get book info
   * @apiSuccess {Object} book The book object.
   * @apiSuccess {String} book.title The title of the book.
   * @apiSuccess {String} book.author The author of the book.
   */
  app.get('/book', (req, res) => {
    const book = new Book('The Great Gatsby', 'F. Scott Fitzgerald');
    res.json({ title: book.getTitle(), author: book.getAuthor() });
  });

  app.listen(3000, () => {
    console.log('App listening on port 3000');
  });

With the above setup, you can easily document your APIs and generate markdown files using JSDoc to Markdown. This ensures that your documentation stays up-to-date and accessible.

Hash: 9a071e47c24aeaea0b1f837aa446f80a7c57ec89dea32acc5321f6ee914e5154