JSDoc 是一个自动化生成 JavaScript 文档工具,它是利用对 JavaScript 函数的特定注释来编译成 HTML 文件的一个文档工具。
安装
全局安装或者局部安装:
npm install jsdoc -g
npm install jsdoc -save-dev
复制代码
基本使用
只要在 JavaScript 中写好注释,利用命令即可:
jsdoc a.js b.js ...
复制代码
当然我们也可以在项目下定义 jsdoc.json
配置文件,通过 -c
参数来指定:
jsdoc -c jsdoc.json
复制代码
可以在 package.json
中的 scripts
添加命令:
{
"scripts": {
"docs": "jsdoc -c jsdoc.json"
}
}
复制代码
这样我们就可以通过在项目下执行 npm run docs
命令来生成文档了。
配置文件
常用的配置文件
{
"source": {
"include": [ "src/" ],
"exclude": [ "src/libs" ]
},
"opts": {
"template": "templates/default",
"encoding": "utf8",
"destination": "./docs/",
"recurse": true,
"verbose": false
}
}
复制代码
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
注释
/**
* @author Mondo
* @description list 数据结构 转换成 树结构
* @param {Array} data 需要转换的数据
* @param {String} id 节点 id
* @param {String} pid 父级节点 id
* @param {String} child 子树为节点对象的某个属性值
* @param {Object} labels 需要新增的字段名集合 { label: 'category_name' }
* @return {Array}
*
* @example
* formatListToTree({data: [{id:1}, {id: 2}, {id: 3, pid: 1}]})
* =>
* [ { id: 1, children: [ {id: 3, pid: 1} ] }, { id: 2 } ]
*/
function formatListToTree({
data = [],
id = "id",
pid = "pid",
child = "children",
labels = null
}) {
...
}
复制代码
常见的 JavaScript 块级注释,必须以 /**
开头,不然会被忽略掉。
下面介绍一些常见的级块标签:
@author
该类/方法的作者。@class
表示这是一个类。@function/@method
表示这是一个函数/方法(这是同义词)。@private
表示该类/方法是私有的,JSDOC 不会为其生成文档。@name
该类/方法的名字。@description
该类/方法的描述。@param
该类/方法的参数,可重复定义。@return
该类/方法的返回类型。@link
创建超链接,生成文档时可以为其链接到其他部分。@example
创建例子。
主题
JSDoc 默认的主题可能不近如人意,不过大型交友网站上给我们提供了还不错的主题,只要我们对应 install
下来配置就行。推荐两款还不错的主题:
配置主题:
下载
npm install docdash --save-dev 复制代码
在
jsdoc.json
文件中配置{ "opts": { "template": "node_modules/docdash" } } 复制代码
模版
对主题还是不满意,我们也可以在 jsdoc.json
中指定自己的模版
{
"templates": {
"cleverLinks": true,
"default": {
"layoutFile": "plugins/layout.tmpl"
}
}
}
复制代码
模版文件其实就是主题中自定义模版。
部署
这一部分可参考 travis-cli 持续集成。
js-utils 是作者君利用 JSDoc 搭建的一个日常函数工具库,可以参考里面的配置。
参考:
jsdoc
欢迎关注公众号,大家一起共同交流和进步。