Sunday, August 26, 2018

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 latest ECMA standards.

Why Javascript Documentation required.

ESDoc is documented API generator for javascript applications, It is written in an ES6 language and It supports writing documentation for ECMA script code. Documentation for any application is critical API for a successful application. It When you are developing API for clients, the first thing for clients to use this API, Good documentation about API description is the important thing. It helps developers to use API with simple
This 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 JSDoc
  • It supports ES5, ES6, ES7 or later
  • Documentation code coverage 
  • Integration with test code
  • Plugin based support for extending to different modules 
  •  Lesser tags that support ES based style syntax
  • This has support ES5 and ES3 javascript versions 
  •  This follows Object-oriented and Prototype-based OOP concepts Many tags to have support
  • Very difficult to extend the functionality

Features

  • It supports javascript documentation for 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 installation successful or not, please issue the below command.
B:\esdocexample>esdoc -v
1.1.0

ESDoc 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 current directory
  3. `.esdoc.js` in current directory
  4. `esdoc` property in package.json
esdoc has a option -c option to configure configuration file. without -c option, By default, it considered .esdoc.json or .esdoc.js file in the current directory esdoc Configuration file This file is global configuration files of a project. Configuration files are considered based on order of the files without esdoc -c option provided. .esdoc.json file .esdoc.js can also configure using esdoc property in package.json esconfig.json
{
  "source": "./src",
  "destination": "./docs",
    "plugins": [
       {
         "name": "esdoc-publish-html-plugin"
        }
      ]
}
the source is javascript source code directory path the destination is a javascript output destination directory plugins - you can configure plugins to extend the functionality.

Generate Documentation 

Here is a javascript code

/**
 *  This is Calculator class
 * @example
 * let class = new Calculator();
 */
export default class Calculator {
 /**
   * this is 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
esdoc javascript documentation generator tool

Related article


EmoticonEmoticon