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