利用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。