安裝
准備
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