利用Gulp實現(xiàn)JSDoc 3的文檔編寫過程中的實時解析和效果預覽

娣辯孩發(fā)布于2019-08-22 10:56 / 3131人閱讀

摘要：所有關于的推薦文章中，都提到了自身配有的一個小工具。說到底還是為了方便實驗以及實驗對的使用，并沒有過多考慮實際生產(chǎn)環(huán)境中的效率問題。

關于不同的Javascript文檔生成工具，可以參考我之前寫的一篇文章《Javascript自動化文檔工具：YUI Doc, JSDoc 3, JSDuck等比較》。本文中則要講講如何能夠基于Gulp構(gòu)建一個快速幫你預覽對應注釋所生成文檔的小工具。

所有關于YUIDoc的推薦文章中，都提到了YUIDoc自身配有的一個小工具：YUIDoc Live Preview。這個工具可以幫助你更快速的預覽你所寫的注釋對應生成的文檔。你只需要保存注釋，然后打開瀏覽器訪問127.0.0.1:3000，就可以看到生成的文檔樣式了。對于尚且不熟悉YUIDoc語法、減少反復跑命令行調(diào)試來說，是一個非常好用的工具。

我非常心儀YUIDoc的這個功能，而且反復在Terminal上跑JSDoc的生成命令實在是太過于麻煩了，于是決定自己動手試試用Gulp在JSDoc 3上實現(xiàn)類似的功能。說到底還是為了方便實驗JSDoc 3以及實驗對Gulp的使用，并沒有過多考慮實際生產(chǎn)環(huán)境中的效率問題。

Gulp是一個類似與Grunt的腳本任務定義、執(zhí)行工具。詳細的關于Gulp的內(nèi)容你可以參考它的官網(wǎng)。它依賴于NodeJS的Stream概念，減少了類似Grunt中對于文件的反復讀寫，同樣的任務使用Gulp的定義確實在我看來比Grunt稍微優(yōu)雅一點。

安裝Gulp

npm install --save-dev gulp

無論是JSDoc還是Gulp都在官方文檔上推薦了Global和local雙重安裝的方式，然而根據(jù)Stackoverflow上的這篇回答，我認為locally安裝可能對于應用的部署確實存在好處。
一方面可以保證用戶始終通過package.json獲取最新/指定的module，另一方面本地安裝不需要sudo權(quán)限，對于用戶的操作帶來了不少便利。即使使用locally安裝，仍然可以通過添加script的方式來使用命令行調(diào)用命令，比如下面的就可以使用npm run test，來調(diào)用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)

上述參數(shù)中的結(jié)構(gòu)如下：

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的執(zhí)行實際分成jsdoc.parser和jsdoc.generator兩步，如果你的程序需要將這兩步分開處理也可以分別調(diào)用這兩個方法。

利用Gulp實現(xiàn)類YUI即時調(diào)試的程序

任務的實現(xiàn)邏輯非常簡單，定義好文檔輸出位置、模版等等生成所需要的信息之后，只需要讓gulp監(jiān)聽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

就可以啟動對于文件夾的監(jiān)聽，保存js的時候自然就會生成最新的文檔，這樣你就可以立刻看到生成的文檔是不是符合你的心意的東西了。另外悄悄的說一句，使用了這樣的方法實驗了幾天對JSDoc 3的使用之后，發(fā)現(xiàn)它的語法真的是太僵硬了，于是棄而轉(zhuǎn)用了JSDuck。

GPU云服務器云服務器 java文檔預覽實現(xiàn) js實現(xiàn)在線文檔預覽 jsdoc-3 招投標過程中的違法行為

文章版權(quán)歸作者所有，未經(jīng)允許請勿轉(zhuǎn)載,若此文章存在違規(guī)行為，您可以聯(lián)系管理員刪除。

轉(zhuǎn)載請注明本文地址：http://systransis.cn/yun/91482.html

JavaScript開發(fā)工具大全

摘要：發(fā)布于之后，采用了完全不同的方式，使用函數(shù)定義任務。它允許開發(fā)者使用它們的補丁和更新來修復這些安全漏洞。提供了工具用于掃描依賴來監(jiān)測漏洞。是一個開源診斷工具，用于和應用。是和開發(fā)的一款新的包管理工具。與相比，它解決了安全性能以及一致性問題。譯者按: 最全的JavaScript開發(fā)工具列表，總有一款適合你！原文: THE ULTIMATE LIST OF JAVASCRIPT TOO...

nifhlheimr 2019-08-20 17:34 評論0 收藏0
前端開發(fā)：實時刷新（及時預覽）工具小匯總，兼有gulp+browser-sync設置方法

摘要：打開您的命令行工具，進入到目錄下，運行以下其中一條命令。將創(chuàng)建一個本地服務器并自動打開你的瀏覽器后訪問地址，這一切都會在命令行工具里顯示。自己寫標簽：實時刷新、免F5、 gulp + browser-sync 開門見山，首先講明一下本文的定位吧：寫這篇文章是因為自己在平時的學習中，一次次試驗了很多的前端實時刷新工具，有順手的，有蹩腳的，有簡單的，有麻煩的，安裝完又折騰，折騰完又卸...

villainhr 2019-08-21 10:47 評論0 收藏0
Javascript自動化文檔工具：YUI Doc, JSDoc 3, JSDuck等比較

摘要：本文比較了種較為主流的注釋文檔生成工具。應該說是非常適合開源項目多個作者共同維護的一個文檔工具。最后我選擇了作為文檔生成的工具。為了支持多種語言，它僅對注釋塊內(nèi)部的內(nèi)容進行解析。最近隨著寫Node以及獨立的CommonJS模塊越來越多，我發(fā)現(xiàn)有一份好的文檔不僅可以幫助自己在應用這些接口的時候不至于迷糊，而且對于共同開發(fā)的情況下，能夠省去大量團隊的交流和Debug的時間。本文比較了...

tyheist 2019-08-22 10:56 評論0 收藏0
前端代碼質(zhì)量進階：自定義 eslint 規(guī)則校驗業(yè)務邏輯

摘要：自定義規(guī)則校驗代碼業(yè)務邏輯是社區(qū)中主流的工具，提供的大量規(guī)則有效的保障了許多項目的代碼質(zhì)量。本文將介紹如何通過自定義檢查規(guī)則，校驗項目中特有的一些業(yè)務邏輯，如特殊作用域特殊使用規(guī)范性等。自定義 eslint 規(guī)則校驗代碼業(yè)務邏輯 eslint 是 JavaScript 社區(qū)中主流的 lint 工具，提供的大量規(guī)則有效的保障了許多項目的代碼質(zhì)量。本文將介紹如何通過自定義 eslint ...

Coly 2019-08-26 11:52 評論0 收藏0
gulp-work-flow 前端工作流原來可以這么簡單

摘要：話不多說，今天的主題是使用打造傳統(tǒng)項目的前端工作流。是一個廣泛使用的轉(zhuǎn)碼器，可以將代碼轉(zhuǎn)為代碼，從而在現(xiàn)有環(huán)境執(zhí)行。這意味著，你可以用的方式編寫程序，又不用擔心現(xiàn)有環(huán)境是否支持。概述最近前端一直是一個火熱的話題，前端技術(shù)棧也是伴隨著nodejs的出現(xiàn)而更替的飛快，導致大部分前端開發(fā)者曾一度迷茫在這各種技術(shù)選型上，比如前端自動化工具就有Grunt，Gulp，Webpack，F(xiàn)is3等...

weakish 2019-08-21 14:27 評論0 收藏0