jsdoc3是一個(gè)比較方便的js代碼生成文檔工具。通過在代碼中加入規(guī)范化的注釋可以快速生成合適的接口文檔，許多IDE工具也逐漸支持jsdoc規(guī)范，擁有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）安裝
運(yùn)行界面輸入cmd打開控制臺(tái)办悟，使用npm安裝（全局安裝）
npm install -g jsdoc
運(yùn)行界面輸入cmd打開控制臺(tái)尘奏，輸入 jsdoc -v，出現(xiàn)下圖表示成功安裝
二病蛉、jsdoc3的基本使用
（1）jsdoc3說(shuō)明文檔
[](https://jsdoc.app)
（2）使用命令打包js
以一個(gè)示例文件jsdoc-test.js為例炫加。這個(gè)文件我放在了E:\mapAPI\docstrap
jsdoc-test.js
1./**
2. * @file
3. * 這是首頁(yè)內(nèi)容展示。
4. * 支持html樣式內(nèi)容
5. * <h3>Grades</h3>
6. */
7./**
8. * @class Grades
9. * 班級(jí)類
10. *
11. */
12.function Grades() {
13. /**
14. * @property {Array} students
15. * 班級(jí)學(xué)生
16. */
17. this.students = [{"name":"學(xué)生1"},{"name":"學(xué)生2"}]
18. /**
19. * @property {String} name
20. * 班級(jí)名稱
21. */
22. this.name = "通信1班"
23. /**
24. * @property {String} headMaster
25. * 班主任
26. */
27. this.headMaster = "班主任1"
28.}
29./**
30. * 獲取班級(jí)學(xué)生
31. * @return {Array} 班級(jí)學(xué)生數(shù)組.{@link Grades#students}
32. */
33.Grades.prototype.getStudents = function() {
34. return this.students;
35.}
36./**
37. * 設(shè)置新班主任
38. * @param {String} headMaster 新班主任名稱
39. */
40.Grades.prototype.setHeadMaster = function(headMaster) {
41. this.headMaster = headMaster;
42.} ?
在jsdoc-test.js目錄下打開控制臺(tái)铺然，輸入:
jsdoc jsdoc-test.js --debug
選項(xiàng): --debug 生成時(shí)控制臺(tái)打印調(diào)試信息俗孝。
回車后如下圖所示，打印了生成的相關(guān)信息
生成后out文件夾中的內(nèi)容如下圖:
點(diǎn)擊html文件打開魄健。每個(gè)html對(duì)應(yīng)一個(gè)頁(yè)面赋铝。生成的文檔頁(yè)面如下圖
三、jsdoc3模板配置與使用
jsdoc3有一些風(fēng)格不錯(cuò)沽瘦，功能豐富的模板革骨。這些模板在上面的jsdoc3的github里可以找到。這里以docstrap模板為例析恋，記錄使用其他模板插件生成文檔頁(yè)面的過程良哲。
docstrap github:https://github.com/docstrap/docstrap
（1）安裝docstrap
使用npm安裝docstrap。在E:\mapAPI\docstrap 打開控制臺(tái)助隧，輸入 npm i ink-docstrap 進(jìn)行安裝
（2）創(chuàng)建模板配置文件
新建一個(gè)jsdoc.conf.json的空文件筑凫，然后填寫配置的內(nèi)容。docstrap的配置方式在遵循jsdoc3配置方式的基礎(chǔ)上，新增加了一些選項(xiàng)巍实。具體的選項(xiàng)說(shuō)明可以在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 打開控制臺(tái)，輸入 jsdoc jsdoc-test.js -c jsdoc.conf.json --debug
此時(shí)當(dāng)前目錄下會(huì)出現(xiàn)一個(gè)test_doc的文件夾棚潦。
里面便是生成好的文檔文件令漂。
效果圖:
四、jsdoc3的gulp插件使用
在上面的安裝好docstrap后丸边，繼續(xù)執(zhí)行安裝gulp-jsdoc3
（1）安裝gulp
在E:\mapAPI\docstrap 打開控制臺(tái)洗显，輸入 npm i gulp@3.9.0
（2）初始化package.json
輸入npm i init生成一個(gè)package.json文件
（3）安裝gulp-jsdoc3等插件包
輸入npm i gulp-jsdoc3 run-sequence 安裝
（4）新建gulpfile文件
新建一個(gè)gulpfile.js,內(nèi)容如下
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）執(zhí)行g(shù)ulp
輸入 gulp ，成功運(yùn)行如下圖所示
當(dāng)js文件發(fā)生變化時(shí)原环，會(huì)自動(dòng)監(jiān)聽并重新打包新的文檔文件,在開發(fā)時(shí)可以邊寫代碼邊生成開發(fā)文檔。
