jsdoc安装与配置

0 环境

本文档采用npm版本为6.11.3

jsdoc官网

1 使用NPM安装JSDoc

首先&＃xff0c;新建一个工程目录&＃xff0c;不妨为jsdoc_demo。创建完成后进入目录

执行

npm init -y


生成一个package.json文件

安装jsdoc

npm i -D jsdoc


package.json中会新增开发依赖配置项

2 配置

jsdoc需要一个配置文件&＃xff0c;如果你不创建它&＃xff0c;jsdoc会使用默认值

首先&＃xff0c;在工程根目录创建一个文件jsdoc.json&＃xff0c;并从官网复制默认内容进去

{"plugins": [],"recurseDepth": 10,"source": {"includePattern": ".&＃43;\\.js(doc|x)?$","excludePattern": "(^|\\/|\\\\)_"},"sourceType": "module","tags": {"allowUnknownTags": true,"dictionaries": ["jsdoc","closure"]},"templates": {"cleverLinks": false,"monospaceLinks": false}
}


具体配置项请阅读官网配置说明&＃xff0c;本文档不深究配置项。下面对该配置文件进行修改&＃xff0c;修改后如下

{"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文件&＃xff0c;添加执行脚本&＃xff0c;下面是脚本添加后的内容

"scripts": {"test": "echo \"Error: no test specified\" && exit 1","doc": "jsdoc -c jsdoc.json"},


3 测试

按照配置&＃xff0c;我们需创建名为src的源文件夹&＃xff0c;该文件夹中的js文件将会自动生成文档。

我们在src下直接创建一个index.js文件。此时&＃xff0c;文件中没有内容&＃xff0c;但我们可以直接执行脚本测试。

执行

npm run doc


我们会发现工程根目录下多了一个docs文件夹&＃xff0c;这是jsdoc按照配置文件的配置生成的。进入docs文件夹&＃xff0c;直接打开index.html查看效果

文档成功生成&＃xff0c;但除了模板啥内容没有

我们在index.js中添加一些内容

// &＃64;ts-check/*** Student Name* &＃64;type {string}*/
const studentName &＃61; &＃39;John Doe&＃39;;


然后再次执行生成文档的脚本&＃xff0c;看下效果

完结。后面的开发按照规范写注释&＃xff0c;即可快速生成文档。