ESDoc 根据 JS 文件注释自动生成接口文档

Question

ESDoc 是一个根据 JavaScript 文件中注释信息，生成 JavaScript 应用程序或库、模块的 API 文档的工具。具有文档覆盖率统计、系统手册、一体化测试、详细接口说明等特点。它可以将测试代码和用户手册一并集成到文档中，支持通过插件添加自定义功能。

生成的项目结构

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){...}

• 网站地址：https://esdoc.org
• GitHub：https://github.com/esdoc/esdoc
• 帮助文档：https://www.wenjiangs.com/docs/esdoc