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

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

閱讀時(shí)間：15分鐘

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

? 如果是之前完全沒(méi)有接觸過(guò)JSDuck或者機(jī)器上沒(méi)有JSDuck環(huán)境，建議可以先花5分鐘看一下筆者的另一篇文章 五分鐘玩轉(zhuǎn)文檔化工具JSDuck。可以先將環(huán)境搭建起來(lái)，對(duì)JSDuck也有一個(gè)可視化的認(rèn)識(shí)。

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

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

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

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

? JS原始類(lèi)型：

? boolean：布爾類(lèi)型

? number：數(shù)值類(lèi)型

? string：字符串類(lèi)型

? void：無(wú)返回值

? undefine：未定義

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

? Number：數(shù)值類(lèi)型

? String：數(shù)值類(lèi)型

? Boolean：布爾類(lèi)型

? Object：對(duì)象

? Array：數(shù)組類(lèi)型

? Date：日期類(lèi)型

? Function：函數(shù)類(lèi)型

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

? Error：錯(cuò)誤類(lèi)型

? Regex：正則對(duì)象

? null：空值

? DOM類(lèi)型：

? HTMLElement：html節(jié)點(diǎn)類(lèi)型

? XMLElement：xml節(jié)點(diǎn)類(lèi)型

? NodeList：DOM節(jié)點(diǎn)集合類(lèi)型

? TextNode：DOM文本節(jié)點(diǎn)類(lèi)型

? CSSStyleSheet：樣式表對(duì)象

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

? Event：DOM事件類(lèi)型

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

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

? JSDuck一共有55個(gè)標(biāo)簽，去除廢棄的和基本不用的標(biāo)簽，還有39個(gè)。其中，通用標(biāo)簽9個(gè)，類(lèi)標(biāo)簽9個(gè)，成員標(biāo)簽15個(gè)，其他標(biāo)簽6個(gè)?，F(xiàn)在我們需要學(xué)習(xí)的僅僅就是這不到40個(gè)標(biāo)簽，而且，這40個(gè)里面有一半的標(biāo)簽使用頻率很低。所以，實(shí)質(zhì)上，我們掌握20個(gè)常用標(biāo)簽就能滿(mǎn)足我們絕大部分的需求了。那么，下面我們就一起來(lái)看看這些標(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)簽，一般情況下和代碼作者一致，如果不一致時(shí)，才會(huì)使用的標(biāo)簽。
@example
示例：
/**
*     
*    @example
*    var pMyClass = new MyClass();
*
* @class MyClass
* My neat class.
* @author John Doe 
*/
文檔示例，使用 @example 標(biāo)簽時(shí)注意要上下都至少空一行并且空四個(gè)。這里也可使用markdown語(yǔ)法代替使用。
樣例還有一種用法，通過(guò)命令參數(shù) --examples 配置示例文件目錄，以頁(yè)面的形式查看示例。
@link
示例：
/**
* 展示非阻擋式消息框，阻擋式彈出框見(jiàn){@link GM.Alert#show GM.Alert}
* @method show
* @param strMessage
*/
內(nèi)部鏈接標(biāo)簽，可以鏈接到文檔其他位置。
@static
表明類(lèi)或成員為靜態(tài)的標(biāo)簽。
@since、@experimental 、@depercated、@new
四個(gè)標(biāo)簽用法一樣，分別表示：代碼版本之后無(wú)效標(biāo)簽、實(shí)驗(yàn)性代碼標(biāo)簽、暫用代碼標(biāo)簽、新增代碼標(biāo)簽。

類(lèi)標(biāo)簽

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

成員標(biāo)簽

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

其他標(biāo)簽

其他標(biāo)簽作用于一些特殊代碼。
@event
語(yǔ)法：
@event name 事件描述
作用于事件，描述事件的標(biāo)簽。
@preventable
作用于事件，表明事件觸發(fā)函數(shù)中，返回false就可以停止冒泡的標(biāo)簽。
@enum
語(yǔ)法：
@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
作用于類(lèi)中屬性，用法同 @param ，描述屬性的標(biāo)簽。
@readonly
作用于類(lèi)中屬性，表明屬性是只讀的標(biāo)簽。
@aside
語(yǔ)法：
@aside guide 
@aside video 
@aside example 
作用于類(lèi)，表明向?qū)У臉?biāo)簽。

? 上面講述了一堆JSDuck的概念和各種標(biāo)簽，那都是在約束我們?nèi)绾尉帉?xiě)代碼和相應(yīng)的注釋。那在這個(gè)基礎(chǔ)上，我們?cè)撊绾问褂眠@個(gè)工具呢？

? JSDuck工具使用起來(lái)其實(shí)非常簡(jiǎn)單，就是幾個(gè)簡(jiǎn)單的cmd命令就可以了。如下圖所示，就是JSDuck的所有命令，一頁(yè)就可以顯示完全，并且我們常用的命令不到10個(gè)。

?

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

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

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

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

? JSDuck是支持使用配置文件來(lái)執(zhí)行命令的，我們只需要在執(zhí)行cmd的目錄下創(chuàng)建一個(gè)名為 jsduck.json 的文件，將所有的配置都寫(xiě)到這個(gè)配置文件里面，然后直接執(zhí)行 jsduck 命令就行了。下面我們貼出一個(gè)標(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"]
}

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

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

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

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

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

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

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

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

"--seo": true,

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

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

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

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

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

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

配置生成的文檔中示例的基準(zhǔn)目錄為當(dāng)前目錄下的 examples文件夾，文檔中需要使用的示例文件都以這個(gè)目錄為基礎(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如果是相對(duì)路徑，就是相對(duì) "--examples-base-url" 中配置的路徑

"--body-html": [
    ""
],

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

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

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

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

require "jsduck/tag/boolean_tag"

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

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

? 馬上回來(lái)，敬請(qǐng)期待哦！

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

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