YuiDoc與JsDoc通用標籤歸納彙總
最近隨著寫Node以及獨立的CommonJS模組越來越多，我發現有一份好的文檔不僅可以幫助自己在應用這些介面的時候不至於迷糊，而且對於共同開發的情況下，能夠省去大量團隊的交流和Debug的時間。然而Javascript註釋文件生成工具多大五六種，每一種的標籤定義還不完全一樣。
Javascript是一個極為靈活的語言，文件生成並不像Java那樣具有絕對統一的規範。YUIDoc與JSDoc用於生成js幫助文件的使用概率非常高，為了方便大夥使用標籤。在這本人將他們的共同標籤進行了抽取，將一部分不常用的並且不同的標籤進行排除。以方便大夥使用。使用如下標籤進行定義我們的js完全可以滿足要求，並且也避免了回頭如果想切換生成工具時標籤不支援的困擾。
一切都是關於標籤
要想將自己的註釋能夠展示到幫助文件中，必須要以兩個*開頭：
|
1 2 3 4 5 6 7 |
/** YUIDoc 會認這個 */ /* 但不認這個 */ |
當然，註釋裡的內容才是最重要的。我們直接進入正題開始從主標籤進行講解
主標籤
開始講主標籤之前，必須明確一點，每個註釋塊中能有且僅有一個主標籤。描述了當前程式碼塊的作用。
@class
@class標籤專門描述類的。在YUI
|
1 2 3 4 |
/** @class Model */ functionModel () {} |
如果你的類是module的一部分，那麼不必在@class註釋裡指明與module的關係，只要檔案的頂部有@module的註釋即可。
@method
@method描述類中的方法。你將會用到@return和@params副標籤加以說明。
@property
@property標籤說明類的屬性值。@type和@default副標籤配合使用。
|
1 2 3 4 |
/** @property templateString */ this.templateString = "div"; |
@event
@event描述你自定義的可觸發事件。YUIDoc文件裡指出:
@event註釋快近似於@method，但無需@return，@param則用於說明回撥方法接收的引數
副標籤
註釋塊可以有多個副標籤，通常同時有幾個並且有些型別相同，下面介紹些常用的：
@namespace
名稱空間；
例子中，最終@class的路徑會顯示為mywidget.Subwidget2
|
1 2 3 4 5 |
/** * Subclass description. * * @constructor * @namespace mywidget * @class SubWidget2 * @extends Accordion */ |
@extends
@extends描述類繼承關係時非常有用，聲明瞭當前類的超類是哪個：
|
1 2 3 4 5 |
/** @class AppView @extends Backbone.View */ varAppView = Backbone.View.extend({}); |
@constructor
如果一個類可被例項化，說明它得有個構造方法。如果你用的是原型鏈的方式，那類的構造也應該是構造方法。那麼下面的註釋就非常常見了：
|
1 2 3 4 5 |
/** @class Recipe @constructor */ functionRecipe () {} |
這事實上是上面提到的@class標籤中應該有一個@constructor或@static的副標籤。
@static
@static是描述那些不能例項化的靜態類的。一個最好的說明就是Math物件，你不必例項化才能呼叫其帶的方法。是通過這個類本身來呼叫的：
|
1 2 3 4 5 |
/** @class MathHelpers @static */ varMathHelpers = {}; |
方法也可以靜態化：可以例項化的類中，可能有些類級別的方法，這些方法被設計成靜態的（只能被類呼叫）。
|
1 2 3 4 5 6 7 8 9 10 11 |
/** @class Person @constructor */ functionPerson () {} /** @method all @static */ Person.all = function() {}; |
本示例中的Person例項的all方法即是靜態的。
@readOnly
本標籤描述屬性和常量：值不可變。由於JS並沒有什麼常量的概念，你編碼的模式規範可能有這樣的要求，那這個標籤就有用了。
|
1 2 3 4 5 |
/** @property DATE_FORMAT @readOnly */ varDATE_FORMAT = "%B %d, %Y"; |
@param
重要標籤：@param定義了@method (包括@constructor) 或@event的引數。@param後寫三個資訊：name 引數名，type引數型別 (可選),，description引數描述。這三個的順序可為name type descriptio或者type namedescription；引數型別必須用{}包括起來。
|
1 2 3 4 5 |
/** @method greet @param person {string} The name of the person to greet */ functiongreet (person) {} |
引數有此可選項，放入[]中表示可選引數，後接著=someVal表明是預設引數 (顯然，只有可靠引數才會有預設值)。用*表示多個引數(name*表示1個或者多個引數，[name]*表示0個或者多個引數)。
|
1 2 3 4 5 6 7 |
/** @class Template @constructor @param template {String} The template string @param [data={}] {Object} The object whose properties will be rendered in the template */ functionTemplate (template, data) {} |
@return
你的方法中通常有返回值，本標籤就可以描述之，別忘記寫上返回值型別和說明。
|
1 2 3 4 5 6 7 8 |
/** @method toHTML @param [template=Recipe.defaultTemplate] {Template} A template object @return {String} The recipe contents formatted in HTML with the default or passed-in template. */ Recipe.prototype.toHTML = function(template) { return"whatever"; }; |
@throws
方法丟擲異常，@throws {type}description 通過帶一個@throws標籤以及可選的type型別，加上描述即可。
|
1 2 3 4 |
/** * @method generateClientId * @throws {Error} An error. */ |
@type
上面提到過主標籤@property。你可能想過定義這些屬性的型別，@type標籤就是給你這麼用的。之後跟著型別，如果多個用|分隔：
|
1 2 3 4 5 6 7 8 9 10 11 |
/** @property URL @type String */ /** @property person @type String|Person|Object */ this.person = newPerson(); |
@private / @protected
傳統語言中都有private 屬性或者方法：不能在例項之外訪問。與常量一樣，JS裡只是練習用的，你可以通過宣告@private來標明。注意，YUIDoc不會在生成的文件中顯示這些屬性或者方法（合理），所以，你可以在程式碼中加入一些對私人有用的資訊。
|
1 2 3 4 5 |
/** @method _toString @private */ var_toString = Object.prototype.toString.call; |
Protected 屬性或者方法是介於public和private之間的：它們只能被例項本身或者子類訪問。如果你的程式碼作用是這樣就用@protected標籤標明。
@requires
如果一個 module 依賴多個module，那就用@requires標明：
|
1 2 3 4 |
/** @module MyFramework.localstorage @requires MyFramework */ |
@requires可用逗號分隔表明同時依賴多個。
@default
宣告一個@property時用@default定義它的預設值，須配合@type用。
|
1 2 3 4 5 6 |
/** @property element @type String @default "div" */ element: "div", |
@example
想在程式碼中加入例項說明？那就用@example標籤，後面縮排一級跟著寫上例項。多少個例項無所謂。
|
1 2 3 4 5 6 |
/** @method greet @example person.greet("Jane"); */ Person.prototype.greet = function(name) {}; |
@deprecated / @since
這兩個標籤說明程式碼的支援性質的(可以是任意程式碼: class, method, 或者其他)。用@deprecated標明程式碼不再可這麼用 (棄用的功能可能在今後的版本更新中被移除)。 你也可以加上點明說為何要這麼做。
|
1 2 3 4 5 |
/** @method toJSON @deprecated Pass the object to `JSON.parse` instead */ Something.toJSON = function() {}; |
@since標籤告訴讀者自哪個版起程式碼被加進來。
|
|