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

娣辯孩發布于2019-08-22 10:56 / 3125人閱讀

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

關于不同的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。

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

文章版權歸作者所有，未經允許請勿轉載,若此文章存在違規行為，您可以聯系管理員刪除。

轉載請注明本文地址：http://specialneedsforspecialkids.com/yun/91482.html

JavaScript開發工具大全

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

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

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

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

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

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

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

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

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

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