JSDoc入门使用指南 -- 手摸手教你用JSDoc（超好用的js文档生成工具）
安装
准备
Node.js 8.15.0+
通过npm安装
全局安装：npm install -g jsdoc
若出现权限问题，如 EACCES报错，最佳实践为用node版本管理器（nvm等）重装npm
本地安装：npm --save-dev jsdoc
命令行工具目录：./node_modules/.bin/jsdoc
鉴于JSDoc的文档生成工具的本质，建议使用 --save-dev的本地安装模式
使用
书写JSDoc标签
jsdoc的使用方式非常简单，在编写代码时根据jsdoc的规则在块级注释中添加相应标签即可：
/**
* 功能：将时间戳格式化为指定格式的字符串
* @param {Number} milliSec - 要转换的时间，可以为秒、毫秒、微秒、或Date类型
* @param {String} [formatStr] - 目标格式字符串 可选 默认为：'yyyy-MM-dd hh:mm:ss'
* @returns {String} - 根据目标时间格式，将时间数值（或Date）转换成的时间字符串
*/
function formatTime(milliSec, formatStr = DEFAULT_FORMAT_STR) {
// code
}
其中 @param、@returns即为jsdoc的常用标签，具体标签及用法可通过传送门到官网或中文文档查看
生成JSDoc文档
代码编写完成后，即可通过命令行生成jsdoc文档
基本用法
/path/to/jsdoc yourSourceCodeFile.js
// 全局安装
jsdoc yourSourceCodeFile.js
// 本地安装
./node_modules/.bin/jsdoc yourSourceCodeFile.js
jsdoc提供了大量命令行选项满足使用需求，这里列出一些常用选项：
-c 或 --configure：指定JSDoc配置文件的路径。默认为安装JSDoc目录下的conf.json或conf.json.EXAMPLE
-d 或 --destination：指定输出生成文档的文件夹路径。JSDoc内置的Haruki模板，使用console 将数据转储到控制台。默认为 ./out
-r 或 --recurse：扫描源文件和导览时递归到子目录
-R 或 --readme：用来包含到生成文档的README.md文件。默认为在源路径中找到的第一个README.md文件
-t 或 --template：用于生成输出文档的模板的路径。默认为templates/default，JSDoc内置的默认模板
-v 或 --version：显示jsdoc版本号
更多选项可通过 -h 或 --help选项查看，或通过传送门到官网或中文文档查看
每次都输入一长串命令行太过繁琐，可在配置文件中的opts参数中指定这些选项
用conf.json配置JSDoc
{
"tags": {
"allowUnknownTags": true
},
"source": {
"include": ["./src"],
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_",
"exclude": ["./src/index.js"]
},
"plugins": [],
"opts": {
"template": "./doc/templates/docdash",
"encoding": "utf8",
"destination": "./doc/doc-page/",
"recurse": true
},
"templates": {
"cleverLinks": false,
"monospaceLinks": false,
"default": {
"outputSourceFiles": true
}
}
}
其中：
tags：控制那些标签允许被使用和解析
source：指定要用jsdoc生成文档的文件
include：路径组成的数组，jsdoc将为它们生成文档
exclude：路径组成的数组，jsdoc应忽略的路径
includePattern：正则表达式字符串，只有文件名匹配的文件才会被jsdoc扫描。默认为 .+.js(doc)?$ 即 .js 或 .jsdoc 结尾的文件才会被扫描
excludePattern：正则表达式字符串，文件名匹配的文件将被jsdoc忽略。默认为 (^|\\/|\\\\)_ 即下划线开头的文件或下划线开头的目录下的所有文件
结合起来，jsdoc的执行过程是：
扫描include中的所有文件（若使用了 -r 命令将在子目录中递归搜索）
在上一步搜索到的文件中，使用includePattern匹配文件名，只保留相匹配的文件
在上一步匹配到的文件中，使用excludePattern匹配文件名，剔除相匹配的文件
在上一部生于的文件中，如果文件路径在exclude中，该文件将被剔除
最终剩下的文件将通过jsdoc进行解析
opts：配置命令行选项，与上面讲的选项相对应
plugins：要启用的插件，在数组中添加插件相对于JSDoc文件夹的路径即可
templates：配置jsdoc所生成的文档的模板
配置完成后使用 ./node_modules/.bin/jsdoc -c path/to/yourconf.json 生成jsdoc文档即可
其他
改变模板
如果你觉得默认模板不好看，可以通过GitHub下载喜欢的模板，例如：
jaguarjs-jsdoc
DocStrap (example)
jsdoc3Template (example)
minami
docdash (example)
tui-jsdoc-template (example)
better-docs (example)
将下载好的模板文件夹放入 ./node_modules/jsdoc/templates/ 中
变更命令行选项中的 template/-t 选项为新的模板文件夹
重新生成jsdoc文档即可
添加主页
主页中可以添加对项目的描述、使用说明、注意事项等等。稳妥起见，我们不采用jsdoc自动搜索的方式
在合适的目录下新建md文件，如 ./doc/HOMEPAGE.md
变更命令行选项中的 readme/-r 为新建的文件 ./doc/HOMEPAGE.md
重新生成jsdoc文档即可
通过npm命令生成文档
如果你仍不满足使用conf.json配置后的命令行简洁程度，可以看过来
打开项目的package.json
在scripts中添加一行 "jsdoc": "node_modules/.bin/jsdoc -r -c doc/conf.json -R doc/HOMEPAGE.md"
执行 npm run jsdoc 即可
gulp中的JSDoc插件：gulp-jsdoc3
安装：npm install --save-dev gulp-jsdoc3
使用：
var jsdoc = require('gulp-jsdoc3');
gulp.task('doc', function (cb) {
// jsdoc的配置文件
var config = require('./doc/conf.json');
gulp.src(['README.md', './src/**/*.js'], {read: false}).pipe(jsdoc(config, cb));
});
传送门
官网：https://jsdoc.app/
GitHub：https://github.com/jsdoc/jsdoc
npm：https://www.npmjs.com/package/jsdoc
中文文档：https://www.html.cn/doc/jsdoc/about-namepaths.html
