0 环境
本文档采用npm版本为6.11.3
jsdoc官网
1 使用NPM安装JSDoc
首先,新建一个工程目录,不妨为jsdoc_demo。创建完成后进入目录
执行
npm init -y
生成一个package.json文件
安装jsdoc
npm i -D jsdoc
package.json中会新增开发依赖配置项
2 配置
jsdoc需要一个配置文件,如果你不创建它,jsdoc会使用默认值
首先,在工程根目录创建一个文件jsdoc.json,并从官网复制默认内容进去
{
"plugins": [],
"recurseDepth": 10,
"source": {
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
},
"sourceType": "module",
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc","closure"]
},
"templates": {
"cleverLinks": false,
"monospaceLinks": false
}
}
具体配置项请阅读官网配置说明,本文档不深究配置项。下面对该配置文件进行修改,修改后如下
{
"plugins": ["plugins/markdown"],
"source": {
"include": ["src"],
"includePattern": ".js$",
"excludePattern": "(node_modules/|docs)"
},
"sourceType": "module",
"templates": {
"cleverLinks": true,
"monospaceLinks": true
},
"opts": {
"recurse": true,
"destination": "./docs/"
}
}
打开package.json文件,添加执行脚本,下面是脚本添加后的内容
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1",
"doc": "jsdoc -c jsdoc.json"
},
3 测试
按照配置,我们需创建名为src的源文件夹,该文件夹中的js文件将会自动生成文档。
我们在src下直接创建一个index.js文件。此时,文件中没有内容,但我们可以直接执行脚本测试。
执行
npm run doc
我们会发现工程根目录下多了一个docs文件夹,这是jsdoc按照配置文件的配置生成的。进入docs文件夹,直接打开index.html查看效果
文档成功生成,但除了模板啥内容没有
我们在index.js中添加一些内容
// @ts-check
/**
* Student Name
* @type {string}
*/
const studentName = 'John Doe';
然后再次执行生成文档的脚本,看下效果
完结。后面的开发按照规范写注释,即可快速生成文档。