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