From Gossip@caterpillar

Ajax Gossip: 編寫 JSDoc

要在JSDoc中編寫文件,基本上很類似於JavaDoc的編寫方式,文件是以/**與*/的區塊包括,當中包括一些文件標籤,如果您編寫過JavaDoc,對這些標籤名稱應不陌生:
  • @author:指定作者名稱。
  • @version:指定版本訊息。
  • @see:建立一個鏈結,指出相關於的類別描述文件。
  • @require:建立一個鏈結,指出必要的類別描述文件。
  • @deprecated:這是個已不建議使用的類別或函式。
  • @param、@argument:描述參數、引數。
  • @return:傳回值描述。
  • @throws、@exception:會丟出的例外之描述。
  • @private:私用成員描述。
  • @final:常數值描述(雖然JavaScript沒有真正的常數值)。
  • @ignore:告知JSDoc忽略這個函式。
  • @class:類別描述。
  • @constructor:建構函式描述。
  • @type:傳回值類型描述。
  • @extends:繼承描述。

您可以參考test.js中的例子,以了解每個標籤實際產生的說明位置,例如:
/**
 * @fileoverview This file is an example of how JSDoc can be used to document
 * JavaScript.
 *
 * @author Ryan Asleson
 * @version 1.0
 */

JSDoc可以為這段文件說明產生以下的內容:


例如:
/**
 * Construct a new Person class.
 * @class This class represents an instance of a Person.
 * @constructor
 * @param {String} name The name of the Person.
 * @return A new instance of a Person.
*/
function Person(name) {
    /**
     * The Person's name
     * @type String
    */
    this.name = name;
    …
}

JSDoc可以為這段文件產生以下的內容: