摘要：語法父類名表示當(dāng)前類繼承于哪個類的標(biāo)簽。成員標(biāo)簽成員標(biāo)簽作用于類中的配置屬性函數(shù)事件。表明可被子類繼承，和一起使用。示例獲取圓的面積圓的半徑面積值作用于函數(shù)，表明函數(shù)的標(biāo)簽。作用于函數(shù)，表明構(gòu)造函數(shù)參數(shù)的標(biāo)簽，用法同。

字?jǐn)?shù)：3692字

閱讀時間：15分鐘

? 首先，咱們有一個前提，JSDuck對我們而言只是一個便于API查看的文檔化工具。因此，只要它能夠滿足我們文檔化的所有需求，并且優(yōu)雅地顯示出來就足夠了。所以，這篇文章旨在告訴大家，在日常工作中，我們?nèi)绾问褂眠@個工具，至于里面的實現(xiàn)原理、編程思想或者自定義標(biāo)簽等咱一概不講。

? 如果是之前完全沒有接觸過JSDuck或者機(jī)器上沒有JSDuck環(huán)境，建議可以先花5分鐘看一下筆者的另一篇文章 五分鐘玩轉(zhuǎn)文檔化工具JSDuck?？梢韵葘h(huán)境搭建起來，對JSDuck也有一個可視化的認(rèn)識。

? 接下來，筆者將從基本概念、標(biāo)簽、工具使用三個方面，和你一起認(rèn)識認(rèn)識JSDuck文檔化工具。

? 提別標(biāo)明一下，文章所有講述的內(nèi)容都是基于當(dāng)前最新的版本JSDuck5

? JSDuck將代碼組成分為兩大部分：類和類中成員。其中，成員又分為配置、屬性、函數(shù)、事件、文檔樣式幾個部分。因此，使用JSDuck有一個基礎(chǔ)——我們的代碼都是以面向?qū)ο蟮姆绞骄帉懙摹?/p>

? 其次，JSDuck的數(shù)據(jù)類型包括JS原始類型、JS內(nèi)嵌類型和DOM類型三大類型。

? JS原始類型：

? boolean：布爾類型

? number：數(shù)值類型

? string：字符串類型

? void：無返回值

? undefine：未定義

? JS內(nèi)嵌類型：

? Number：數(shù)值類型

? String：數(shù)值類型

? Boolean：布爾類型

? Object：對象

? Array：數(shù)組類型

? Date：日期類型

? Function：函數(shù)類型

? Arguments：函數(shù)參數(shù)

? Error：錯誤類型

? Regex：正則對象

? null：空值

? DOM類型：

? HTMLElement：html節(jié)點類型

? XMLElement：xml節(jié)點類型

? NodeList：DOM節(jié)點集合類型

? TextNode：DOM文本節(jié)點類型

? CSSStyleSheet：樣式表對象

? CSSStyleRule：樣式規(guī)則對象

? Event：DOM事件類型

? 這些數(shù)據(jù)類型都是JSDuck默認(rèn)支持的數(shù)據(jù)類型，它們都是我們在寫代碼文檔時可以直接使用的數(shù)據(jù)類型。此外，JSDuck還支持我們自定義數(shù)據(jù)類型，不過絕大多數(shù)情況下，這些數(shù)據(jù)類型已經(jīng)足夠我們使用了。

? JSDuck擁有超級豐富的標(biāo)簽，這也正是它功能強(qiáng)大的體現(xiàn)之一。其實學(xué)習(xí)這個工具的80%的學(xué)習(xí)成本都在標(biāo)簽的學(xué)習(xí)上，也就是說弄清楚了這些標(biāo)簽，那我們基本上就掌握了這門工具了。而且，其實在我們學(xué)習(xí)這些標(biāo)簽時，不僅是了解他們的用法，我們更多的是學(xué)習(xí)到這些標(biāo)簽背后的代碼規(guī)范、設(shè)計思路和編程思想。廢話不多說了，咱就開始JSDuck標(biāo)簽的學(xué)習(xí)吧！

? JSDuck一共有55個標(biāo)簽，去除廢棄的和基本不用的標(biāo)簽，還有39個。其中，通用標(biāo)簽9個，類標(biāo)簽9個，成員標(biāo)簽15個，其他標(biāo)簽6個?，F(xiàn)在我們需要學(xué)習(xí)的僅僅就是這不到40個標(biāo)簽，而且，這40個里面有一半的標(biāo)簽使用頻率很低。所以，實質(zhì)上，我們掌握20個常用標(biāo)簽就能滿足我們絕大部分的需求了。那么，下面我們就一起來看看這些標(biāo)簽的用法吧！

通用標(biāo)簽

通用標(biāo)簽作用于所有代碼。
@author
示例：
/**
* @class MyClass
* My neat class.
* @author John Doe 
*/

表示代碼作者的標(biāo)簽。
@docauthor
示例：
/**
* @class MyClass
* My neat class.
* @author John Doe 
* @docauthor Tom 
*/
表示文檔作者的標(biāo)簽，一般情況下和代碼作者一致，如果不一致時，才會使用的標(biāo)簽。
@example
示例：
/**
*     
*    @example
*    var pMyClass = new MyClass();
*
* @class MyClass
* My neat class.
* @author John Doe 
*/
文檔示例，使用 @example 標(biāo)簽時注意要上下都至少空一行并且空四個。這里也可使用markdown語法代替使用。
樣例還有一種用法，通過命令參數(shù) --examples 配置示例文件目錄，以頁面的形式查看示例。
@link
示例：
/**
* 展示非阻擋式消息框，阻擋式彈出框見{@link GM.Alert#show GM.Alert}
* @method show
* @param strMessage
*/
內(nèi)部鏈接標(biāo)簽，可以鏈接到文檔其他位置。
@static
表明類或成員為靜態(tài)的標(biāo)簽。
@since、@experimental 、@depercated、@new
四個標(biāo)簽用法一樣，分別表示：代碼版本之后無效標(biāo)簽、實驗性代碼標(biāo)簽、暫用代碼標(biāo)簽、新增代碼標(biāo)簽。

類標(biāo)簽

類標(biāo)簽只作用于類。
@class
語法：
@class 類名
表示類的標(biāo)簽。
@extends
語法：
@extends 父類名
表示當(dāng)前類繼承于哪個類的標(biāo)簽。
@alias、@alternateClassName
分別表示類的別名標(biāo)簽、類的說明標(biāo)簽。
@abstract
表明抽象類的標(biāo)簽。
@requires
示例：
/**
* @class TestClass
* @requires TestClass3
* @requires TestClass4
*/
表明當(dāng)前類依賴的類，可以有多個依賴類。
@uses
表明當(dāng)前類使用了那些類，可以有多個。
@mixins
表明多態(tài)類標(biāo)簽，當(dāng)前類中混合了其他類的成員。
@singleton
表明當(dāng)前類為單例模式類。

成員標(biāo)簽

成員標(biāo)簽作用于類中的配置、屬性、函數(shù)、事件。
@member
語法：
@member 類名
表明當(dāng)前成員屬于哪一個類，如果代碼中該成員已經(jīng)屬于某個類，則會自動分析出來，不需要添加該標(biāo)記。
@private、@protected
分別表明當(dāng)前成員是私有成員和受保護(hù)成員的標(biāo)簽。
@hide
文檔中，子類不需要展示出來的其父類的成員標(biāo)簽。
@inheritable
表明可被子類繼承，和@static一起使用。
@removed
表明成員已經(jīng)被刪除標(biāo)簽。
@method
示例：
/**
* @method area
* 獲取圓的面積
* @param {Number} r 圓的半徑
* @return {Number} 面積值
*/
作用于函數(shù)，表明函數(shù)的標(biāo)簽。
@param
語法：
@param name
@param {Type} name
@param {Type} [name]
@param {Type} [name="default-value"]
@param {Type} name.subproperty
作用于函數(shù)，表明函數(shù)參數(shù)的標(biāo)簽。
@constructor
作用于函數(shù)，表明函數(shù)是類的構(gòu)造函數(shù)的標(biāo)簽。
@cfg
作用于函數(shù)，表明構(gòu)造函數(shù)參數(shù)的標(biāo)簽，用法同 @param。
@return
語法：
@return {Type} 返回說明
@return {Type} return.subproperty
作用于函數(shù)，表明函數(shù)返回值標(biāo)簽，沒有返回值就不需要添加該標(biāo)簽。
@abstract
作用于函數(shù)，表明函數(shù)是抽象函數(shù)的標(biāo)簽。
@chainable
作用于函數(shù)，表明函數(shù)是鏈?zhǔn)胶瘮?shù)的標(biāo)簽。如果代碼中直接返回this，則工具會自動識別為鏈?zhǔn)胶瘮?shù)。
@throws
語法
@throws 錯誤描述
@throws {Type} 錯誤描述
作用于函數(shù)，表明函數(shù)報錯時拋出的異常標(biāo)簽，可以添加多個標(biāo)簽表明多個異常，錯誤類型默認(rèn)是 object 類型。
@fires
語法：
@fires eventName
作用于函數(shù)，表明當(dāng)前函數(shù)會觸發(fā)哪個事件的標(biāo)簽。

其他標(biāo)簽

其他標(biāo)簽作用于一些特殊代碼。
@event
語法：
@event name 事件描述
作用于事件，描述事件的標(biāo)簽。
@preventable
作用于事件，表明事件觸發(fā)函數(shù)中，返回false就可以停止冒泡的標(biāo)簽。
@enum
語法：
@enum
@enum {Type}
@enum {Type} EnumName
@enum [EnumName=alias.*]

示例：
/** @enum */
MyEnum = {
 /** the first enum value */
 FIRST: "foo",
 /** the second enum value */
 SECOND: "bar"
};
表明枚舉的標(biāo)簽。
@property
作用于類中屬性，用法同 @param ，描述屬性的標(biāo)簽。
@readonly
作用于類中屬性，表明屬性是只讀的標(biāo)簽。
@aside
語法：
@aside guide 
@aside video 
@aside example 
作用于類，表明向?qū)У臉?biāo)簽。

? 上面講述了一堆JSDuck的概念和各種標(biāo)簽，那都是在約束我們?nèi)绾尉帉懘a和相應(yīng)的注釋。那在這個基礎(chǔ)上，我們該如何使用這個工具呢？

? JSDuck工具使用起來其實非常簡單，就是幾個簡單的cmd命令就可以了。如下圖所示，就是JSDuck的所有命令，一頁就可以顯示完全，并且我們常用的命令不到10個。

?

部分命令參數(shù)如下：

? 這里要注意一點，JSDuck所有的參數(shù)都需要添加兩個 “-”。例如，最常用的命令就是 ：

? jsduck "G: est-jsduck est.js" --output=G: est-jsduckdoc

? 這條命令的意思就是將文件 G:test-jsducktest.js 中的代碼生成文檔，然后存放到目錄 G:test-jsduckdoc 下。這是最簡單的一條命令，這個命令之后可以添加上面列出的任何參數(shù)。但是每次我們都去敲一堆命令行來執(zhí)行工具確實有點繁瑣，下面我們一起試試更便捷的方法吧！

? JSDuck是支持使用配置文件來執(zhí)行命令的，我們只需要在執(zhí)行cmd的目錄下創(chuàng)建一個名為 jsduck.json 的文件，將所有的配置都寫到這個配置文件里面，然后直接執(zhí)行 jsduck 命令就行了。下面我們貼出一個標(biāo)準(zhǔn)的配置文件看看：

{
    "--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": [
        ""
    ],
    "--tags":["tags/my_custom_tag.rb"]
}

? 如果想省事情，可以直接把這段配置拷貝過去，按照自己的實際環(huán)境設(shè)置一下屬性，就可以直接使用了。下面，我們一起來解讀一下這段配置的含義。

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

配置文檔在瀏覽器中顯示的標(biāo)簽名稱和頁面的標(biāo)題名稱為 “XXX文檔”。

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

配置文檔歡迎頁面的路徑為“welcome.html”，這里配置的是相對當(dāng)前運(yùn)行命令的路徑。

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

配置生成文檔時，遇到未知的連接或缺失文檔的代碼時，不生成警告日志。參數(shù)值里面，“-”表示

關(guān)閉警告，“+”表示打開警告，查看詳細(xì)警告信息可以鍵入jsduck --help=warings

"--seo": true,

配置生成文檔時，進(jìn)行SEO優(yōu)化。

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

配置需要生成文檔的內(nèi)容，這里我配置了一個集合，里面包含了三個目錄，這三個目錄下所有的文件都會被掃描并生成文檔。這里，我們也可以配置到具體的一個文件。

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

配置生成的文檔文件的保存目錄為當(dāng)前目錄下的 docs 文件夾。

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

配置生成的文檔中示例的基準(zhǔn)目錄為當(dāng)前目錄下的 examples文件夾，文檔中需要使用的示例文件都以這個目錄為基礎(chǔ)路徑。

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

配置示例文件路徑為當(dāng)前目錄下名為 examples.json 的文件，文件內(nèi)容如下：

[
   {
       "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": [
    ""
],

配置生成的文檔頁面中，body內(nèi)需要添加的額外內(nèi)容，頁面元素表現(xiàn)如下圖所示：

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

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

配置自定義標(biāo)簽，我們這里是配置了一個ruby代碼文件路徑，自定義了一種標(biāo)識成員為內(nèi)部成員的標(biāo)簽。這里就需要我們具備一點ruby的知識了，該文件代碼如下：

require "jsduck/tag/boolean_tag"

class Inner < JsDuck::Tag::BooleanTag
  def initialize
    @pattern = "inner"
    @signature = {:long => "inner", :short => "in"}
    super
  end
end
這就是一個自定義一個布爾類型的簡單標(biāo)簽的示例代碼。還有許多更復(fù)雜的標(biāo)簽定義方式，但是好在JSDuck提供的標(biāo)簽已經(jīng)相當(dāng)豐富了，絕大多數(shù)情況下，我們是不需要自定義標(biāo)簽的。

? 至此，JSDuck的基本用法就已經(jīng)全部介紹完畢啦！到這里的大家也已經(jīng)擁有獨立使用JSDuck所需的所有知識儲備了，接下來我們?nèi)钡闹挥袑崙?zhàn)了。下一篇文章，筆者將和大伙一起實戰(zhàn)一把，探討一下怎樣才是使用JSDuck的正確姿勢。

? 馬上回來，敬請期待哦！

? 除了該文章以外，筆者還特制了一份思維導(dǎo)圖，以作飯后甜點食用： 一張圖之——JSDuck 。

歡迎關(guān)注我的微信公眾號：