原文地址: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){...}