關於不一樣的Javascript文檔生成工具,能夠參考我以前寫的一篇文章《Javascript自動化文檔工具:YUI Doc, JSDoc 3, JSDuck等比較》。本文中則要講講如何可以基於Gulp構建一個快速幫你預覽對應註釋所生成文檔的小工具。html
全部關於YUIDoc的推薦文章中,都提到了YUIDoc自身配有的一個小工具:YUIDoc Live Preview。這個工具能夠幫助你更快速的預覽你所寫的註釋對應生成的文檔。你只須要保存註釋,而後打開瀏覽器訪問127.0.0.1:3000,就能夠看到生成的文檔樣式了。對於尚且不熟悉YUIDoc語法、減小反覆跑命令行調試來講,是一個很是好用的工具。node
我很是心儀YUIDoc的這個功能,並且反覆在Terminal上跑JSDoc的生成命令實在是太過於麻煩了,因而決定本身動手試試用Gulp在JSDoc 3上實現相似的功能。說到底仍是爲了方便實驗JSDoc 3以及實驗對Gulp的使用,並無過多考慮實際生產環境中的效率問題。git
Gulp是一個相似與Grunt的腳本任務定義、執行工具。詳細的關於Gulp的內容你能夠參考它的官網。它依賴於NodeJS的Stream概念,減小了相似Grunt中對於文件的反覆讀寫,一樣的任務使用Gulp的定義確實在我看來比Grunt稍微優雅一點。github
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...npm
"devDependencies": { "gulp": "latest" } "scripts": { "test": "gulp test" }
npm install --save-dev gulp-jsdoc
jsdoc最主要的方法以下:json
jsdoc(destination, template, infos, options)
上述參數中的結構以下:gulp
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兩步,若是你的程序須要將這兩步分開處理也能夠分別調用這兩個方法。segmentfault
任務的實現邏輯很是簡單,定義好文檔輸出位置、模版等等生成所須要的信息以後,只須要讓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。