Generates Javascript Documentation - ESDoc Tool

In my previous post, We covered the javascript documentation tool using JSDoc.

In this blog post, We are going to learn the ESDoc tool-generated documentation for Javascript and the latest ECMA standards.

Why Javascript Documentation is required?

ESDoc is documented API generator for javascript applications, It is written in an ES6 language. It supports writing documentation for ECMA script code.

Documentation for any application is a critical API for a successful application. When you are developing an API for clients, the first thing for clients to use this API is, Good documentation about API description is important thing. It helps developers to use API with simple

It is based on plugin-based architecture. Everything is based on plugin configuration. EsDoc parses the tags from comments of a javascript and generates HTML documentation.

DIfference between ESDoc and JSDoc tool

JSDoc is a popular Javascript documentation API generator. ESDoc follows the same approach.

ESDoc Features

• It supports javascript documentation for the latest ECMAScript
• Documentation code coverage
• Test coverage into the documentation
• Can be hosted independently
• Support ECMAScript proposals spec

Installation and Setup ESDoc

It provides npm packages. First You need to install ESDoc and esdoc standard plugin to use esdoc tool

npm install --save-dev esdoc esdoc-standard-plugin

This installation provides esdoc command-line tool. To check whether the installation is successful or not, please issue the below command.

B:\esdocexample>esdoc -v
1.1.0

ESDoc command line Options

B:\esdocexample>esdoc -h
Usage: esdoc [-c esdoc.json]

Options:
  -c specify config file
  -h output usage information
  -v output the version number

ESDoc finds configuration by the order:
  1. `-c your-esdoc.json`
  2. `.esdoc.json` in the current directory
  3. `.esdoc.js` in the current directory
  4. `esdoc` property in package.json

esdoc has an option -c option to configure configuration files. without -c option, i.e default, it considered .esdoc.json or .esdoc.js file in the current directory,i.e esdoc Configuration file. the file is the global configuration file of a project.

Configuration files are considered based on the order of the files without _esdoc -c optio_n provided. .esdoc.json file .esdoc.js can also configure using the esdoc property in package.json esconfig.json

{
  "source": "./src",
  "destination": "./docs",
  "plugins": [
    {
      "name": "esdoc-publish-html-plugin"
    }
  ]
}

the source is the javascript source code directory path the destination is a javascript output destination directory plugin - you can configure plugins to extend the functionality.

How to Generate Documentation using esdoc command line

Here is a javascript code

/**
 *  This is Calculator class
 * @example
 * let class = new Calculator();
 */
export default class Calculator {
  /**
   * this is the Calculator constructor description.
   */
  constructor() {}
  /**
   * addition of two numbers
   * @param {number} param1  number to add.
   * @param {number} param2 number to add.
   * @return {number} returns sum of two parameters.
   */
  add(param1, param2) {
    return param1 + param2;
  }
  /**
   * this is method description.
   * @returns {string} this is return description.
   */
  method() {
    return "message";
  }
}

We will use esdoc command-line tool to generate HTML documentation. Please use the below command to generate it.

esdoc
// -c option for  esdoc custom configuration
esdoc -c esdoc.json
//  esdoc installed locally, using local esdoc tool
./node_modules/.bin/esdoc -c esdoc.json

Here is a command output

B:\esdocexample>esdoc
parse: B:\esdocexample\src\Calculator.js
resolve: extends chain
resolve: necessary
resolve: ignore
resolve: link
resolve: markdown in description
resolve: test relation
output: B:\esdocexample\docs\identifiers.html
output: B:\esdocexample\docs\index.html
output: B:\esdocexample\docs\class\src\Calculator.js~Calculator.html
output: B:\esdocexample\docs\file\src\Calculator.js.html
output: B:\esdocexample\docs\css
output: B:\esdocexample\docs\script
output: B:\esdocexample\docs\image
output: B:\esdocexample\docs\script\search_index.js
output: B:\esdocexample\docs\source.html

Here is the output of HTML generation file