esdoc 自動生成接口文檔介紹

原文地址：https://www.xingkongbj.com/blog/esdoc/creat-esdoc.html

官網

• ESDoc：https://esdoc.org/
• JSDoc：http://usejsdoc.org/

介紹

ESDoc 是一個根據 javascript 文件中注釋信息，生成 JavaScript 應用程序或庫、模塊的 API 文檔的工具。具有文檔覆蓋率統計、系統手冊、一體化測試、詳細接口說明等特點。

ESDoc 與 JSDoc 對比

JSDoc 是目前最火的文檔生成工具，它存在的時間也比較長，但是功能上還欠缺一些，比如文檔覆蓋率、自動測試、搜索等，都沒有實現。並且它的使用比較復雜，需要嚴格使用標簽，過多依賴備注來實現。它最大的坑是同名接口無法區分。

	ESDoc	JSDoc
ES標准	ES6 以上	ES6
模塊化	Class、import & export	Class、import & export、CommonJS、AMD、Prototype
注釋類型	塊級注釋	塊級注釋
標簽	少量標簽	標簽完善，需要嚴格使用
文檔內容	自動語義化，說明詳細	注釋中提煉
覆蓋率	支持	無
測試	支持	無
手冊	支持多個文檔	支持多個文檔
搜索	支持	無
插件	支持	支持
同名接口	重疊顯示	分開顯示

示例

https://try.esdoc.org/
點擊左上角 Try it out

Home

讀取根目錄 README.md 文件，可以用於記錄項目基本信息。

Manual

讀取本地配置的 markdown 文件，可以用於記錄項目相關資料。

Reference

接口的詳細說明，根據注釋自動生產。

Source

接口的源代碼，同時提供文檔覆蓋率查看。

Test

接口的測試，主要用於純 JS 代碼。

安裝和使用

// 安裝
npm install --save-dev esdoc esdoc-standard-plugin

// 使用
./node_modules/.bin/esdoc

配置文件

項目根目錄 .esdoc.json

// esdoc 配置，react版
{
  "source": "./app", // 需要生成文檔的 js 主目錄
  "destination": "./esdocs", // 輸出目錄
  "includes": [
    "\\.(js|jsx|vue)$" // 包含的匹配正則
  ],
  "excludes": [
    "(bundle\\.js|export\\.js)$" // 排除的匹配正則
  ],
  "index": "./README.md",  // 首頁引入文件
  "package": "./package.json", // package 配置文件
  "outputAST": true, // 輸出結構樹
  "plugins": [
    { "name": "esdoc-standard-plugin", // 基礎插件
      "option": {
        "manual": {
          "index": "./manual/index.md",
          "files": [
            "./manual/directory.md"
          ]
        }
      }
    },
    { "name": "esdoc-jsx-plugin", "option": { "enable": true } },  // 支持 jsx 語法
    { "name": "esdoc-ecmascript-proposal-plugin", "option": { "all": true } }, // 支持 es 新語法
    { "name": "esdoc-react-plugin" }, // 支持 react 語法
    {
      "name": "esdoc-importpath-plugin", // 支持 import 路徑修改
      "option": {
        "stripPackageName": true,
        "replaces": [
          {"from": "^app/page/", "to": "page/"},
          {"from": "^app/component/", "to": "component/"},
          {"from": "^app/module/", "to": "module/"},
          {"from": "^app/reactTools/", "to": "tools/"},
          {"from": "^app/middlewares/", "to": "middlewares/"}
        ]
      }
    }
  ]
}

自動接入工具 eslint-init

接入工具安裝

$ npm i -g esdoc-init

接入

# 目前只支持 react 項目
$ esdoc-init # 在有 package.json 文件的項目根目錄 

運行 esdoc

# 在有 package.json 文件的項目根目錄
$ npm run esdoc

常用標簽

@public--對外接口，一般可以省略

@private--內部接口，使用 "_" 可以省略

@protected--受保護接口

/**
 * @public
 */
class MyClass {
    /**
     * @private
     */
    _method(){...}
    
    /**
     * @protected
     */
    add(){...}
}

@deprecated--接口廢棄，會顯示在文檔中

/**
 * @deprecated 使用 MyClassEx 替換
 */
class MyClass{...}

@ignore--忽略接口，不會顯示在文檔中

/**
 * @ignore
 */
class MyClass{...}

@version--標注版本號

/**
 * @version 0.0.1
 */
class MyClass{...}

@todo--后期需要實現功能

/**
 * @todo 支持修改
 */
class MyClass{...}

@extends--繼承自，一般能自動識別

/**
 * @extends {SuperClass1}
 * @extends {SuperClass2}
 */
class MyClass extends mix(SuperClass1, SuperClass2) {...}

@param--參數，支持對象

class App extends MFEComponent {
    /**
     * 初始化
     * @param {Object} props - 傳入對象
     * @param {Number} props.foo - 描述
     * @param {String} props.bar - 描述
     */
    constructor(props){...}
}

@return--返回值，支持對象

class MyClass {
    /**
     * @return {Object} 描述
     * @property {number} foo - 描述
     * @property {number} bar - 描述
     */
    method(){...}
}

@type--類型定義

// 單個屬性
class MyClass {
    constructor() {
        /** @type {number} */
        this.p = 123;
    
        /**
         * @type {Object}
         * @property {number} res.foo - 描述
         * @property {string} res.bar - 描述
         */
        this.res = {foo: 123, bar: "abc"};
    }
}

// get/set
class MyClass {
  /** @type {string} */
  get value() {}

  /** @type {string} */
  set value(v){}
}

類型語法

數組

/**
 * @param {number[]} param - 描述
 */
function myFunc(param){...}

並存類型

/**
 * @param {number|string} param - 描述
 */
function myFunc(param){...}