ESDoc 是一个支持 ECMAScript 2015(ES6)、React JSX 和 Flow 的文档生成工具，它可以通过注释自动生成 JavaScript 代码的文档。同时，ESDoc 还提供了非常易用的在线文档查看工具。
在这里，我们介绍一下 ESDoc 的一个 npm 包 esdoc-livescript 的使用，通过 esdoc-livescript，我们可以使用 Livescript 语法来编写注释文档，同时还支持其他 ESDoc 功能，例如：JSX 语法、Flow 类型注解。
安装
直接通过 npm 安装 esdoc-livescript:
npm i esdoc-livescript --save-dev
安装成功后，我们可以在项目的 node_modules 目录下找到 esdoc-livescript 的相关文件。
配置
在项目的根目录下新增配置文件 esdoc.json，并进行相应的配置。
{
"source": "./src",
"destination": "./docs",
"plugins": [{
"name": "esdoc-livescript-plugin",
"option": {}
}]
}其中 source 表示源码目录，destination 表示文档生成目录。plugins 下是一个个插件的设置项，其中 name 表示插件名称，option 表示插件的配置选项。
注释文档
注释文档分为单行注释和多行注释，下面给出具体示例。
单行注释
单行注释以 @ 字符作为标识符，它表示要添加的文档信息。例如：
# @param {Number} a - 参数 a。
# @param {Number} b - 参数 b。
add = (a, b) ->
a + b上述代码中，我们使用单行注释为函数 add 添加了两个参数的文档信息，分别表示参数 a 和参数 b 的类型。
多行注释
多行注释中，第一行是注释的摘要，摘要后面可以添加多行详细说明，多行注释中，同样以 @ 字符作为标识符，例如：
-- -------------------- ---- -------
--
- ---------
-
- ------ -------- - - -- --
- ------ -------- - - -- --
- -------- -------- ---- - --- - ----
--
-------- - --- -- --
- - -上述代码中，我们为函数 multiply 添加了摘要和详细说明的注释文档。
运行生成文档
首先，我们需要在 package.json 中添加一条 npm script：
{
"scripts": {
"doc": "esdoc"
}
}然后，在命令行运行：
npm run doc
这时，ESDoc 便会在我们在配置 esdoc.json 中设置的 destination 目录下自动生成文档了。
结论
通过 esdoc-livescript，我们可以使用 Livescript 语法来编写注释文档，并使用 ESDoc 自动生成文档，这对于我们在前端开发中进行代码框架搭建、文档编写以及代码维护都有着很大的实用性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6005583181e8991b448d55f0