jsdoc3是一个比较方便的js代码生成文档工具。通过在代码中加入规范化的注释可以快速生成合适的接口文档，许多IDE工具也逐渐支持jsdoc规范，拥有jsdoc插件，如Hbuilder,VSCode,Submile Text等。
在使用jsdoc3之前，还需要安装Node.js。Node.js 安装配置|菜鸟教程。
一、jsdoc3的下载安装
（1）jsdoc3开源地址:
github：https://github.com/jsdoc/jsdoc
码云：https://gitee.com/mirrors/JsDoc3
（2）安装
运行界面输入cmd打开控制台，使用npm安装（全局安装）
npm install -g jsdoc
运行界面输入cmd打开控制台，输入 jsdoc -v，出现下图表示成功安装
二、jsdoc3的基本使用
（1）jsdoc3说明文档
[](https://jsdoc.app)
（2）使用命令打包js
以一个示例文件jsdoc-test.js为例。这个文件我放在了E:\mapAPI\docstrap
jsdoc-test.js
1./**
2. * @file
3. * 这是首页内容展示。
4. * 支持html样式内容
5. * <h3>Grades</h3>
6. */
7./**
8. * @class Grades
9. * 班级类
10. *
11. */
12.function Grades() {
13. /**
14. * @property {Array} students
15. * 班级学生
16. */
17. this.students = [{"name":"学生1"},{"name":"学生2"}]
18. /**
19. * @property {String} name
20. * 班级名称
21. */
22. this.name = "通信1班"
23. /**
24. * @property {String} headMaster
25. * 班主任
26. */
27. this.headMaster = "班主任1"
28.}
29./**
30. * 获取班级学生
31. * @return {Array} 班级学生数组.{@link Grades#students}
32. */
33.Grades.prototype.getStudents = function() {
34. return this.students;
35.}
36./**
37. * 设置新班主任
38. * @param {String} headMaster 新班主任名称
39. */
40.Grades.prototype.setHeadMaster = function(headMaster) {
41. this.headMaster = headMaster;
42.}
在jsdoc-test.js目录下打开控制台，输入:
jsdoc jsdoc-test.js --debug
选项: --debug 生成时控制台打印调试信息。
回车后如下图所示，打印了生成的相关信息
生成后out文件夹中的内容如下图:
点击html文件打开。每个html对应一个页面。生成的文档页面如下图
三、jsdoc3模板配置与使用
jsdoc3有一些风格不错，功能丰富的模板。这些模板在上面的jsdoc3的github里可以找到。这里以docstrap模板为例，记录使用其他模板插件生成文档页面的过程。
docstrap github:https://github.com/docstrap/docstrap
（1）安装docstrap
使用npm安装docstrap。在E:\mapAPI\docstrap 打开控制台，输入 npm i ink-docstrap 进行安装
（2）创建模板配置文件
新建一个jsdoc.conf.json的空文件，然后填写配置的内容。docstrap的配置方式在遵循jsdoc3配置方式的基础上，新增加了一些选项。具体的选项说明可以在github中查看。以下是我在用的配置模板
jsdoc.conf.json
{
"tags":{
"allowUnknownTags":true
},
"opts":{
"template":"./node_modules/ink-docstrap/template",
"encoding":"utf8",
"destination":"./test_doc/",
"recurse":true
},
"plugins":["plugins/markdown"],
"recurseDepth":10,
"source":{
"includePattern":".+\\.js(doc|x)?$",
"excludePattern":"(^|\\/|\\\\)_"
},
"templates":{
"logoFile":"",
"cleverLinks":false,
"monospaceLinks":false,
"dateFormat":"dddMMMDoYYYY",
"outputSourceFiles":true,
"outputSourcePath":true,
"systemName":"",
"footer":"",
"copyright":"",
"navType":"vertical",
"theme":"cosmo",
"linenums":true,
"collapseSymbols":false,
"inverseNav":true,
"protocol":"html://",
"methodHeadingReturns":false,
"search":true
},
"markdown":{
"parser":"gfm",
"hardwrap":true
}
}
（3）生成文档
在E:\mapAPI\docstrap 打开控制台，输入 jsdoc jsdoc-test.js -c jsdoc.conf.json --debug
此时当前目录下会出现一个test_doc的文件夹。
里面便是生成好的文档文件。
效果图:
四、jsdoc3的gulp插件使用
在上面的安装好docstrap后，继续执行安装gulp-jsdoc3
（1）安装gulp
在E:\mapAPI\docstrap 打开控制台，输入 npm i gulp@3.9.0
（2）初始化package.json
输入npm i init生成一个package.json文件
（3）安装gulp-jsdoc3等插件包
输入npm i gulp-jsdoc3 run-sequence 安装
（4）新建gulpfile文件
新建一个gulpfile.js,内容如下
1.let gulp = require('gulp');
2.let jsdoc = require('gulp-jsdoc3');
3.
4.gulp.task('doc', function (cb) {
5. var config = require('./jsdoc.conf');
6. gulp.src(['README.md', './js/**/*.js'], {read: false})
7. .pipe(jsdoc(config, cb));
8.});
9.
10.gulp.task('default', function (cb) {
11. let runSequence = require('run-sequence');
12. runSequence('doc', cb);
13.
14. gulp.watch(['./js/**/*.js'],["doc"]);
15.});
（5）执行gulp
输入 gulp ，成功运行如下图所示
当js文件发生变化时，会自动监听并重新打包新的文档文件,在开发时可以边写代码边生成开发文档。
