JSDuck用法詳解

時間 2019-11-10

標籤 jsduck 用法詳解简体版

原文原文鏈接

字數：3692字 javascript

閱讀時間：15分鐘css

前言

首先，我們有一個前提，JSDuck對咱們而言只是一個便於API查看的文檔化工具。所以，只要它可以知足咱們文檔化的全部需求，而且優雅地顯示出來就足夠了。因此，這篇文章旨在告訴你們，在平常工做中，咱們如何使用這個工具，至於裏面的實現原理、編程思想或者自定義標籤等咱一律不講。html

若是是以前徹底沒有接觸過JSDuck或者機器上沒有JSDuck環境，建議能夠先花5分鐘看一下筆者的另外一篇文章五分鐘玩轉文檔化工具JSDuck。能夠先將環境搭建起來，對JSDuck也有一個可視化的認識。java

接下來，筆者將從基本概念、標籤、工具使用三個方面，和你一塊兒認識認識JSDuck文檔化工具。web

提別標明一下，文章全部講述的內容都是基於當前最新的版本JSDuck5編程

1.基本概念

JSDuck將代碼組成分爲兩大部分：類和類中成員。其中，成員又分爲配置、屬性、函數、事件、文檔樣式幾個部分。所以，使用JSDuck有一個基礎——咱們的代碼都是以面向對象的方式編寫的。json

其次，JSDuck的數據類型包括JS原始類型、JS內嵌類型和DOM類型三大類型。數組

JS原始類型： 瀏覽器

boolean：布爾類型ruby

number：數值類型

string：字符串類型

void：無返回值

undefine：未定義

JS內嵌類型：

Number：數值類型

String：數值類型

Boolean：布爾類型

Object：對象

Array：數組類型

Date：日期類型

Function：函數類型

Arguments：函數參數

Error：錯誤類型

Regex：正則對象

null：空值

DOM類型：

HTMLElement：html節點類型

XMLElement：xml節點類型

NodeList：DOM節點集合類型

TextNode：DOM文本節點類型

CSSStyleSheet：樣式表對象

CSSStyleRule：樣式規則對象

Event：DOM事件類型

這些數據類型都是JSDuck默認支持的數據類型，它們都是咱們在寫代碼文檔時能夠直接使用的數據類型。此外，JSDuck還支持咱們自定義數據類型，不過絕大多數狀況下，這些數據類型已經足夠咱們使用了。

2.標籤

JSDuck擁有超級豐富的標籤，這也正是它功能強大的體現之一。其實學習這個工具的80%的學習成本都在標籤的學習上，也就是說弄清楚了這些標籤，那咱們基本上就掌握了這門工具了。並且，其實在咱們學習這些標籤時，不只是瞭解他們的用法，咱們更多的是學習到這些標籤背後的代碼規範、設計思路和編程思想。廢話很少說了，咱就開始JSDuck標籤的學習吧！

JSDuck一共有55個標籤，去除廢棄的和基本不用的標籤，還有39個。其中，通用標籤9個，類標籤9個，成員標籤15個，其餘標籤6個。如今咱們須要學習的僅僅就是這不到40個標籤，並且，這40個裏面有一半的標籤使用頻率很低。因此，實質上，咱們掌握20個經常使用標籤就能知足咱們絕大部分的需求了。那麼，下面咱們就一塊兒來看看這些標籤的用法吧！

通用標籤

通用標籤做用於全部代碼。

@author
示例：
/**
* @class MyClass
* My neat class.
* @author John Doe <john@example.com>
*/
表示代碼做者的標籤。

@docauthor
示例：
/**
* @class MyClass
* My neat class.
* @author John Doe <john@example.com>
* @docauthor Tom <Tom@example.com>
*/
表示文檔做者的標籤，通常狀況下和代碼做者一致，若是不一致時，纔會使用的標籤。

@example
示例：
/**
*     
*    @example
*    var pMyClass = new MyClass();
*
* @class MyClass
* My neat class.
* @author John Doe <john@example.com>
*/
文檔示例，使用 @example 標籤時注意要上下都至少空一行而且空四個。這裏也可以使用markdown語法代替使用。

樣例還有一種用法，經過命令參數 --examples 配置示例文件目錄，以頁面的形式查看示例。

@link
示例：
/**
* 展現非阻擋式消息框，阻擋式彈出框見{@link GM.Alert#show GM.Alert}
* @method show
* @param strMessage
*/
內部連接標籤，能夠連接到文檔其餘位置。

@static

代表類或成員爲靜態的標籤。

@since、@experimental 、@depercated、@new

四個標籤用法同樣，分別表示：代碼版本以後無效標籤、實驗性代碼標籤、暫用代碼標籤、新增代碼標籤。

類標籤

類標籤只做用於類。

@class
語法：
@class 類名
表示類的標籤。

@extends
語法：
@extends 父類名
表示當前類繼承於哪一個類的標籤。

@alias、@alternateClassName

分別表示類的別名標籤、類的說明標籤。

@abstract

代表抽象類的標籤。

@requires
示例：
/**
* @class TestClass
* @requires TestClass3
* @requires TestClass4
*/
代表當前類依賴的類，能夠有多個依賴類。

@uses

代表當前類使用了那些類，能夠有多個。

@mixins

代表多態類標籤，當前類中混合了其餘類的成員。

@singleton

代表當前類爲單例模式類。

成員標籤

成員標籤做用於類中的配置、屬性、函數、事件。

@member
語法：
@member 類名
代表當前成員屬於哪個類，若是代碼中該成員已經屬於某個類，則會自動分析出來，不須要添加該標記。

@private、@protected

分別代表當前成員是私有成員和受保護成員的標籤。

@hide

文檔中，子類不須要展現出來的其父類的成員標籤。

@inheritable

代表可被子類繼承，和@static一塊兒使用。

@removed

代表成員已經被刪除標籤。

@method
示例：
/**
* @method area
* 獲取圓的面積
* @param {Number} r 圓的半徑
* @return {Number} 面積值
*/
做用於函數，代表函數的標籤。

@param
語法：
@param name
@param {Type} name
@param {Type} [name]
@param {Type} [name="default-value"]
@param {Type} name.subproperty
做用於函數，代表函數參數的標籤。

@constructor

做用於函數，代表函數是類的構造函數的標籤。

@cfg

做用於函數，代表構造函數參數的標籤，用法同 @param。

@return
語法：
@return {Type} 返回說明
@return {Type} return.subproperty
做用於函數，代表函數返回值標籤，沒有返回值就不須要添加該標籤。

@abstract

做用於函數，代表函數是抽象函數的標籤。

@chainable

做用於函數，代表函數是鏈式函數的標籤。若是代碼中直接返回this，則工具會自動識別爲鏈式函數。

@throws
語法
@throws 錯誤描述
@throws {Type} 錯誤描述
做用於函數，代表函數報錯時拋出的異常標籤，能夠添加多個標籤代表多個異常，錯誤類型默認是 object 類型。

@fires
語法：
@fires eventName
做用於函數，代表當前函數會觸發哪一個事件的標籤。

其餘標籤

其餘標籤做用於一些特殊代碼。

@event
語法：
@event name 事件描述
做用於事件，描述事件的標籤。

@preventable

做用於事件，代表事件觸發函數中，返回false就能夠中止冒泡的標籤。

@enum
語法：
@enum
@enum {Type}
@enum {Type} EnumName
@enum [EnumName=alias.*]

示例：
/** @enum */
MyEnum = {
 /** the first enum value */
 FIRST: 'foo',
 /** the second enum value */
 SECOND: 'bar'
};
代表枚舉的標籤。

@property

做用於類中屬性，用法同 @param ，描述屬性的標籤。

@readonly

做用於類中屬性，代表屬性是隻讀的標籤。

@aside
語法：
@aside guide <name>
@aside video <name>
@aside example <name>
做用於類，代表嚮導的標籤。

3.工具使用

上面講述了一堆JSDuck的概念和各類標籤，那都是在約束咱們如何編寫代碼和相應的註釋。那在這個基礎上，咱們該如何使用這個工具呢？

JSDuck工具使用起來其實很是簡單，就是幾個簡單的cmd命令就能夠了。以下圖所示，就是JSDuck的全部命令，一頁就能夠顯示徹底，而且咱們經常使用的命令不到10個。

部分命令參數以下：

參數	含義
-- 或空	須要生成文檔的文件或者目錄，也能夠是一個集合
--output	文檔存放的目錄
--config	配置文件路徑
--encoding	文檔編碼方式
--exclude	不生成文檔的目錄或文件，能夠是一個集合
--title	文檔標題
--footer	文檔標尾
--head-html	文檔頁面的head中須要添加的內容
--body-html	文檔頁面的body中須要添加的內容
--css	額外添加的樣式
--welcome	歡迎頁面
--guides	嚮導配置
--examples	示例配置
--categories	分類配置
--images	圖片路徑配置
--tags	自定義標籤
--examples-base-url	示例文件的基礎路徑
--help	查看命令幫助
--version	查看當前版本

這裏要注意一點，JSDuck全部的參數都須要添加兩個「-」。例如，最經常使用的命令就是：

jsduck "G:\test-jsduck\test.js" --output=G:\test-jsduck\doc

這條命令的意思就是將文件 G:test-jsducktest.js 中的代碼生成文檔，而後存放到目錄 G:test-jsduckdoc 下。這是最簡單的一條命令，這個命令以後能夠添加上面列出的任何參數。可是每次咱們都去敲一堆命令行來執行工具確實有點繁瑣，下面咱們一塊兒試試更便捷的方法吧！

JSDuck是支持使用配置文件來執行命令的，咱們只須要在執行cmd的目錄下建立一個名爲 jsduck.json 的文件，將全部的配置都寫到這個配置文件裏面，而後直接執行 jsduck 命令就好了。下面咱們貼出一個標準的配置文件看看：

{
    "--title": "XXX文檔",
    "--welcome": "welcome.html",
    "--warnings": ["-link", "-no_doc"],
    "--seo": true,
    "--": [
        "./common/js",
        "./custom",
        "./libs/angular/custom"
    ],
    "--output": "./docs",
    "--examples-base-url": "./examples",
    "--examples": "./examples.json",
    "--body-html": [
        "<script type='text/javascript'>",
        "Docs.otherProducts = [",
            "{text: 'Docs 3.0', href: 'http://***/3.0'},",
            "{text: 'Docs 2.0', href: 'http://***/2.0'},",
            "{text: 'Docs 1.0', href: 'http://***/1.0'}",
        "];",
        "</script>"
    ],
    "--tags":["tags/my_custom_tag.rb"]
}

若是想省事情，能夠直接把這段配置拷貝過去，按照本身的實際環境設置一下屬性，就能夠直接使用了。下面，咱們一塊兒來解讀一下這段配置的含義。

"--title": "XXX文檔",

配置文檔在瀏覽器中顯示的標籤名稱和頁面的標題名稱爲「XXX文檔」。

"--welcome": "welcome.html",

配置文檔歡迎頁面的路徑爲「welcome.html」，這裏配置的是相對當前運行命令的路徑。

"--warnings": ["-link", "-no_doc"],

配置生成文檔時，遇到未知的鏈接或缺失文檔的代碼時，不生成警告日誌。參數值裏面，「-」表示

關閉警告，「+」表示打開警告，查看詳細警告信息能夠鍵入jsduck --help=warings

"--seo": true,

配置生成文檔時，進行SEO優化。

"--": [
        "./common/js",
        "./custom",
        "./libs/angular/custom"
    ],

配置須要生成文檔的內容，這裏我配置了一個集合，裏面包含了三個目錄，這三個目錄下全部的文件都會被掃描並生成文檔。這裏，咱們也能夠配置到具體的一個文件。

"--output": "./docs",

配置生成的文檔文件的保存目錄爲當前目錄下的 docs 文件夾。

"--examples-base-url": "./examples",

配置生成的文檔中示例的基準目錄爲當前目錄下的 examples文件夾，文檔中須要使用的示例文件都以這個目錄爲基礎路徑。

"--examples": "./examples.json",

配置示例文件路徑爲當前目錄下名爲 examples.json 的文件，文件內容以下：

[
   {
       "title": "Combination Examples",
       "items": [
           {
               "name": "feed-viewer",
               "title": "Feed Viewer",
               "description": "RSS feed reader example application.",
               "url": "feed-viewer.html",
               "icon": "G:/codeWorkSpace/idea/static-resources/src/main/webapp/custom/frame/frame2/img/user.png",
               "status": "updated"
           },
           {
               "name": "web-desktop",
               "text": "Web Desktop",
               "description": "A desktop in the browser using Ext components.",
               "url": "http://www.example.com/desktop.html",
               "icon": "/../../custom/frame/frame2/img/user.png",
               "status": "updated"
           }
       ]
   }
]

其中，url若是是相對路徑，就是相對 "--examples-base-url" 中配置的路徑

"--body-html": [
    "<script type='text/javascript'>",
    "Docs.otherProducts = [",
    "{text: 'Docs 3.0', href: 'http://***/3.0'},",
    "{text: 'Docs 2.0', href: 'http://***/2.0'},",
    "{text: 'Docs 1.0', href: 'http://***/1.0'}",
    "];",
    "</script>"
],

配置生成的文檔頁面中，body內須要添加的額外內容，頁面元素表現以下圖所示：

這裏我是配置了一個版本列表的下拉菜單，裏面包含了這個文檔的1.0、2.0、3.0版本的連接。

"--tags":["tags/my_custom_tag.rb"]

配置自定義標籤，咱們這裏是配置了一個ruby代碼文件路徑，自定義了一種標識成員爲內部成員的標籤。這裏就須要咱們具有一點ruby的知識了，該文件代碼以下：

require "jsduck/tag/boolean_tag"

class Inner < JsDuck::Tag::BooleanTag
  def initialize
    @pattern = "inner"
    @signature = {:long => "inner", :short => "in"}
    super
  end
end
這就是一個自定義一個布爾類型的簡單標籤的示例代碼。還有許多更復雜的標籤訂義方式，可是好在JSDuck提供的標籤已經至關豐富了，絕大多數狀況下，咱們是不須要自定義標籤的。

至此，JSDuck的基本用法就已經所有介紹完畢啦！到這裏的你們也已經擁有獨立使用JSDuck所需的全部知識儲備了，接下來咱們缺的只有實戰了。下一篇文章，筆者將和大夥一塊兒實戰一把，探討一下怎樣纔是使用JSDuck的正確姿式。

立刻回來，敬請期待哦！

除了該文章之外，筆者還特製了一份思惟導圖，以做飯後甜點食用：一張圖之——JSDuck 。

歡迎關注個人微信公衆號：