JS 工具库文档化

JSDoc 是一个自动化生成 JavaScript 文档工具，它是利用对 JavaScript 函数的特定注释来编译成 HTML 文件的一个文档工具。

安装

全局安装或者局部安装：

1npm install jsdoc -g
2
3npm install jsdoc -save-dev
4复制代码

基本使用

只要在 JavaScript  中写好注释，利用命令即可：

1jsdoc a.js b.js ...
2复制代码

当然我们也可以在项目下定义 jsdoc.json 配置文件，通过 -c 参数来指定：

1jsdoc -c jsdoc.json
2复制代码

可以在 package.json 中的 scripts 添加命令：

1{
2	"scripts": {
3  	"docs": "jsdoc -c jsdoc.json"
4  }
5}
6复制代码

这样我们就可以通过在项目下执行 npm run docs 命令来生成文档了。

配置文件

常用的配置文件

1{
2  "source": {
3    "include": [ "src/" ],
4    "exclude": [ "src/libs" ]
5  },
6  "opts": {
7    "template": "templates/default",
8    "encoding": "utf8",
9    "destination": "./docs/",
10    "recurse": true,
11    "verbose": false
12  }
13}
14复制代码

• source 表示传递给 JSDOC 的文件
• source.include 表示 JSDOC 需要扫描哪些文件
• source.exclude 表示 JSDOC 需要排除哪些文件
• opts 表示传递给 JSDOC 的选项
• opts.template 生成文档的模板，默认是 templates/default
• opts.encoding 读取文件的编码，默认是 utf8
• opts.destination 生成文档的路径，默认是 ./out/
• opts.recurse 运行时是否递归子目录
• opts.verbose 运行时是否输出详细信息，默认是 false

注释

1/**
2* @author Mondo
3* @description list 数据结构 转换成 树结构
4* @param {Array} data 需要转换的数据
5* @param {String} id 节点 id
6* @param {String} pid 父级节点 id
7* @param {String} child 子树为节点对象的某个属性值
8* @param {Object} labels 需要新增的字段名集合 { label: 'category_name' }
9* @return {Array}
10*
11* @example
12* formatListToTree({data: [{id:1}, {id: 2}, {id: 3, pid: 1}]})
13* =>
14* [ { id: 1, children: [ {id: 3, pid: 1} ] }, { id: 2 } ]
15*/
16
17function formatListToTree({
18  data = [],
19  id = "id",
20  pid = "pid",
21  child = "children",
22  labels = null
23}) {
24...
25}
26复制代码

常见的 JavaScript 块级注释，必须以 /** 开头，不然会被忽略掉。

下面介绍一些常见的级块标签：

• @author 该类/方法的作者。
• @class 表示这是一个类。
• @function/@method 表示这是一个函数/方法(这是同义词)。
• @private 表示该类/方法是私有的，JSDOC 不会为其生成文档。
• @name 该类/方法的名字。
• @description 该类/方法的描述。
• @param 该类/方法的参数，可重复定义。
• @return 该类/方法的返回类型。
• @link 创建超链接，生成文档时可以为其链接到其他部分。
• @example 创建例子。

主题

JSDoc 默认的主题可能不近如人意，不过大型交友网站上给我们提供了还不错的主题，只要我们对应 install 下来配置就行。推荐两款还不错的主题：

• docdash
• minami

配置主题：

• 下载

  npm install docdash --save-dev 复制代码

• 在 jsdoc.json 文件中配置

  { "opts": { "template": "node_modules/docdash" } } 复制代码

模版

对主题还是不满意，我们也可以在 jsdoc.json  中指定自己的模版

1{
2  "templates": {
3    "cleverLinks": true,
4    "default": {
5      "layoutFile": "plugins/layout.tmpl"
6    }
7  }
8}
9复制代码

模版文件其实就是主题中自定义模版。

部署

这一部分可参考 travis-cli 持续集成。

js-utils 是作者君利用 JSDoc  搭建的一个日常函数工具库，可以参考里面的配置。

参考：
jsdoc

欢迎关注公众号，大家一起共同交流和进步。