透過註解 與 JSDoc 產生開發文件 自動產生專案文件

me
林彥成
2017-01-27 | 1 min.

來介紹一下一個厲害又方便攻城獅偷懶的工具 JSDoc,透過註解可以在短短幾秒內自動生成出網頁版的文件。

安裝

只要下指令安裝 npm install jsdoc,然後就可以直接 jsdoc yourJavaScriptFile.js 使用了 Orz 不過檔案內容當然要搭配上特殊的註解 /** 開頭,這樣才可以被 jsdoc 辨識出來,下面是官網的範例:

1
2
3
4
5
6
7
/**
* Represents a book.
* @constructor
* @param {string} title - The title of the book.
* @param {string} author - The author of the book.
*/
function Book(title, author) {}

配置檔

這麼普及的東西,想當然爾可以整合進 gulp 中,只要記得先裝上 gulp-jsdoc3 XD 不喜歡預設值的話,可以加上自定義的簡單配置檔:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
"tags": {
"allowUnknownTags": true,
"dictionaries": ["jsdoc", "closure"]
},
"source": {
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
},
"plugins": [],
"templates": {
"cleverLinks": false,
"monospaceLinks": false,
"includeDate": false
},
"opts": {
"encoding": "utf8",
"recurse": true,
"destination": "./doc/"
}
}

整合進 gulp

接著在 gulp-jsdoc3 中配置套用後,只要告訴 jsdoc 需要幫哪些檔案做文件:

1
2
3
4
5
6
7
8
var jsdoc = require("gulp-jsdoc3");

gulp.task("doc", function (cb) {
var config = require("./conf.json");
gulp
.src(["README.md", "./js/**/*.js"], { read: false })
.pipe(jsdoc(config, cb));
});

就可以早早收工洗洗睡了 Orz


喜歡這篇文章,請幫忙拍拍手喔 🤣

share