摘要：所有关于的推荐文章中，都提到了自身配有的一个小工具。说到底还是为了方便实验以及实验对的使用，并没有过多考虑实际生产环境中的效率问题。
关于不同的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稍微优雅一点。
安装Gulpnpm 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监听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。
文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。
转载请注明本文地址：https://www.ucloud.cn/yun/91482.html
摘要：发布于之后，采用了完全不同的方式，使用函数定义任务。它允许开发者使用它们的补丁和更新来修复这些安全漏洞。提供了工具用于扫描依赖来监测漏洞。是一个开源诊断工具，用于和应用。是和开发的一款新的包管理工具。与相比，它解决了安全性能以及一致性问题。 译者按: 最全的JavaScript开发工具列表，总有一款适合你！ 原文: THE ULTIMATE LIST OF JAVASCRIPT TOO...
摘要：打开您的命令行工具，进入到目录下，运行以下其中一条命令。将创建一个本地服务器并自动打开你的浏览器后访问地址，这一切都会在命令行工具里显示。 自己写标签： 实时刷新、 免F5、 gulp + browser-sync 开门见山，首先讲明一下本文的定位吧：写这篇文章是因为自己在平时的学习中，一次次试验了很多的前端实时刷新工具，有顺手的，有蹩脚的，有简单的，有麻烦的，安装完又折腾，折腾完又卸...
摘要：本文比较了种较为主流的注释文档生成工具。应该说是非常适合开源项目多个作者共同维护的一个文档工具。最后我选择了作为文档生成的工具。为了支持多种语言，它仅对注释块内部的内容进行解析。 最近随着写Node以及独立的CommonJS模块越来越多，我发现有一份好的文档不仅可以帮助自己在应用这些接口的时候不至于迷糊，而且对于共同开发的情况下，能够省去大量团队的交流和Debug的时间。 本文比较了...
摘要：自定义规则校验代码业务逻辑是社区中主流的工具，提供的大量规则有效的保障了许多项目的代码质量。本文将介绍如何通过自定义检查规则，校验项目中特有的一些业务逻辑，如特殊作用域特殊使用规范性等。 自定义 eslint 规则校验代码业务逻辑 eslint 是 JavaScript 社区中主流的 lint 工具，提供的大量规则有效的保障了许多项目的代码质量。本文将介绍如何通过自定义 eslint ...
摘要：话不多说，今天的主题是使用打造传统项目的前端工作流。是一个广泛使用的转码器，可以将代码转为代码，从而在现有环境执行。这意味着，你可以用的方式编写程序，又不用担心现有环境是否支持。 概述 最近前端一直是一个火热的话题，前端技术栈也是伴随着nodejs的出现而更替的飞快，导致大部分前端开发者曾一度迷茫在这各种技术选型上，比如前端自动化工具就有Grunt，Gulp，Webpack，Fis3等...
阅读 3607·2021-09-02 15:11
阅读 4517·2021-08-16 10:47
阅读 1532·2019-08-29 18:35
阅读 3013·2019-08-28 17:54
阅读 2826·2019-08-26 11:37
阅读 1475·2019-08-23 16:51
阅读 1781·2019-08-23 14:36
阅读 1785·2019-08-23 14:21
