JavaScript 軟體工程

透過註解 與 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