生成Javascript文档 - ESDoc工具

在这篇博文中，我们将学习ESDoc工具为Javascript和最新的ECMA标准生成的文档。

为什么需要Javascript文档。

ESDoc是为javascript应用程序生成文档的API，它是用ES6语言编写的，它支持为ECMA脚本代码编写文档。任何应用程序的文档是一个成功的应用程序的关键API。当你为客户开发API时，客户使用这个API的第一件事，好的API描述文档是很重要的事情。它可以帮助开发者以简单的方式使用API，这是基于插件的架构。一切都是基于插件的配置。EsDoc解析javascript注释中的标签并生成HTML文档。

JSDoc是一个流行的Javascript文档API生成器。ESDoc也遵循同样的方法。

ESDoc

JSDoc

• 它支持ES5、ES6、ES7或更高版本

• 文档代码覆盖率

• 与测试代码集成

• 基于插件的支持，可以扩展到不同的模块

• 支持基于ES风格语法的较少的标签

• 支持ES5和ES3的javascript版本

• 遵循面向对象和基于原型的OOP概念 许多标签都有支持

• 非常难以扩展功能

特点

• 它支持最新的ECMAScript的javascript文档
• 文档的代码覆盖率
• 测试覆盖到文档中
• 可以独立托管
• 支持ECMAScript建议规范

安装和设置ESDoc

它提供了npm包，首先你需要安装ESDoc和esdoc标准插件来使用esdoc工具。

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

这个安装提供了esdoc命令行工具。要检查安装成功与否，请发出以下命令。

B:\esdocexample>esdoc -v
1.1.0

ESDoc选项

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有一个选项-c，用来配置配置文件。如果没有-c选项，默认情况下，它会考虑当前目录下的.esdoc.json或.esdoc.js文件。 esdoc配置文件 该文件是一个项目的全局配置文件。在没有提供_esdoc -c选项的情况下，会根据文件的顺序来考虑配置文件。.esdoc.json文件 .esdoc.js也可以使用package.json中的esdoc属性进行配置 esconfig.json

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

来源是javascript源代码目录路径 目标是javascript输出目标目录插件 - 你可以配置插件来扩展功能。

生成文档

这里是一个javascript代码

/**
 *  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';
  }
}

我们将使用esdoc命令行工具来生成HTML文档。请使用下面的命令来生成它。

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

这里是一个命令输出

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

这里是HTML生成文件的输出