利用Gulp實現JSDoc 3的文檔編寫過程當中的實時解析和效果預覽

關於不一樣的Javascript文檔生成工具，能夠參考我以前寫的一篇文章《Javascript自動化文檔工具：YUI Doc, JSDoc 3, JSDuck等比較》。本文中則要講講如何可以基於Gulp構建一個快速幫你預覽對應註釋所生成文檔的小工具。

全部關於YUIDoc的推薦文章中，都提到了YUIDoc自身配有的一個小工具：YUIDoc Live Preview。這個工具能夠幫助你更快速的預覽你所寫的註釋對應生成的文檔。你只須要保存註釋，而後打開瀏覽器訪問127.0.0.1:3000，就能夠看到生成的文檔樣式了。對於尚且不熟悉YUIDoc語法、減小反覆跑命令行調試來講，是一個很是好用的工具。

我很是心儀YUIDoc的這個功能，並且反覆在Terminal上跑JSDoc的生成命令實在是太過於麻煩了，因而決定本身動手試試用Gulp在JSDoc 3上實現相似的功能。說到底仍是爲了方便實驗JSDoc 3以及實驗對Gulp的使用，並無過多考慮實際生產環境中的效率問題。

---

Gulp是一個相似與Grunt的腳本任務定義、執行工具。詳細的關於Gulp的內容你能夠參考它的官網。它依賴於NodeJS的Stream概念，減小了相似Grunt中對於文件的反覆讀寫，一樣的任務使用Gulp的定義確實在我看來比Grunt稍微優雅一點。

安裝Gulp

npm install --save-dev gulp

不管是JSDoc仍是Gulp都在官方文檔上推薦了Global和local雙重安裝的方式，然而根據Stackoverflow上的這篇回答，我認爲locally安裝可能對於應用的部署確實存在好處。
一方面能夠保證用戶始終經過package.json獲取最新/指定的module，另外一方面本地安裝不須要sudo權限，對於用戶的操做帶來了很多便利。即便使用locally安裝，仍然能夠經過添加script的方式來使用命令行調用命令，好比下面的就可使用npm run test，來調用gulp test命令而不是加上./node-module/bin...

"devDependencies": {
     "gulp": "latest"
}
"scripts": {
     "test": "gulp test"
}

gulp-jsdoc插件

npm install --save-dev gulp-jsdoc

jsdoc最主要的方法以下：

jsdoc(destination, template, infos, options)

上述參數中的結構以下：

template ＝ {
     path: 'path_to_template',
     anyTemplateSpecificParameter: 'whatever'
}

infos = {
     name: ''    //定義項目的名稱，同時在des中會生成對應的folder，便於管理多個項目
     description: ''   
     version: ''  //定義項目的版本，同時會在項目的folder裏面生成版本的folder，用於管理不一樣版本的文檔
     licenses: []
     plugins: false    //type: []
}

options = {
    'private': false,
    monospaceLinks: false,
    cleverLinks: false,
    outputSourceFiles: true
}

目前Gulp的方式尚且不能支持Tutorial和conf.json中source的過濾。
jsdoc的執行實際分紅jsdoc.parser和jsdoc.generator兩步，若是你的程序須要將這兩步分開處理也能夠分別調用這兩個方法。

利用Gulp實現類YUI即時調試的程序

任務的實現邏輯很是簡單，定義好文檔輸出位置、模版等等生成所須要的信息以後，只須要讓gulp監聽src文件夾下對js文件的修改就能夠了。

var gulp = require('gulp'),
    jsdoc = require("gulp-jsdoc");

gulp.task('generate', function(){
     return gulp.src("./src/*.js")
            .pipe(jsdoc('./documentation-output'))
});
gulp.task('watch', function(){
     gulp.watch('./src/*.js', ['generate']);
});
gulp.task('default', ['generate']);

一切就緒以後，你只須要

gulp watch

就能夠啓動對於文件夾的監聽，保存js的時候天然就會生成最新的文檔，這樣你就能夠馬上看到生成的文檔是否是符合你的心意的東西了。另外悄悄的說一句，使用了這樣的方法實驗了幾天對JSDoc 3的使用以後，發現它的語法真的是太僵硬了，因而棄而轉用了JSDuck。