应用Gulp完成JSDoc 3的文档编写过程当中的及时剖析和结果预览

2019年8月26日 171次阅读 来源: yeelan0319

关于差别的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。

    原文作者：yeelan0319
    原文地址: https://segmentfault.com/a/1190000002583569
    本文转自网络文章，转载此文章仅为分享知识，如有侵权，请联系博主进行删除。
点赞