背景
为一个 React 项目添加 JavaScript 文档。
目标
文档覆盖范围：UI 组件、业务组件、辅助函数
解决方案
使用 ESDoc + plugin。
具体步骤：
1. 安装 ESDoc
yarn add --dev esdoc esdoc-standard-plugin
配置 .esdoc.json
{
"source": "./src",
"destination": "./docs",
"plugins": [{"name": "esdoc-standard-plugin"}]
}
运行 esdoc
yarn esdoc && open ./docs/index.html
这时，ESDoc 已经可以为普通 js 文件生成文档了，但是对 React 组件还是无能为力。
会出现下面错误：
warning: could not parse the following code. if you want to use ECMAScript proposals, see https://esdoc.org/manual/feature.html#ecmascript-proposal
原因： React 组件语法是 JSX 语法，和 ECMAScript 语法不一样。
2. 安装 2 个 plugin: esdoc-ecmascript-proposal-plugin、esdoc-jsx-plugin
yarn add --dev esdoc-external-ecmascript-plugin esdoc-jsx-plugin
配置 .esdoc.json
{
"source": "./src",
"destination": "./doc",
"plugins": [
{"name": "esdoc-standard-plugin"},
{"name": "esdoc-external-ecmascript-plugin", "option": {"enable": true}},
{"name": "esdoc-jsx-plugin", "option": {"enable": true}}
]
}
运行 esdoc
yarn esdoc && open ./docs/index.html
配置到这里就结束了。
上图：
