編輯“Ajax- 使用JSDoc建立JavaScript代碼的文檔”（章節(jié)）

== 用法 ==


既然對JSDoc已經有所了解，你可能想知道如何使用JSDoc來為你的JavaScript代碼生成文檔。表5-1列出了可以創(chuàng)建HTML文檔的一些特殊JSDoc標記。這些標記對于曾在Java代碼中編寫過javadoc注釋的人員并不陌生。包含在生成文檔中的每個注釋塊都必須以/**開頭，并以*/結束。 <br>

JSDoc命令屬性<br>

命 令 名<br>
描    述<br>
 
@param<br>

@argument<br>
指定參數名和說明來描述一個函數參數<br>
 
@return<br>

@returns<br>
描述函數的返回值<br>
 
@author<br>
指示代碼的作者<br>
 
@deprecated<br>
 指示一個函數已經廢棄，而且在將來的代碼版本中將徹底刪除。要避免使用這段代碼<br>
 
@see<br>
創(chuàng)建一個HTML鏈接，指向指定類的描述<br>
 
@version<br>
指定發(fā)布版本<br>
 
@requires<br>
創(chuàng)建一個HTML鏈接，指向這個類所需的指定類<br>
 
@throws<br>

@exception<br>
描述函數可能拋出的異常的類型<br>
 
{@link}<br>
創(chuàng)建一個HTML鏈接，指向指定的類。這與@see很類似，但{@link}能嵌在注釋文本中<br>
 
@fileoverview<br>
這是一個特殊的標記。如果在文件的第一個文檔塊中使用這個標記，則指定該文檔塊的余下部分將用來提供這個文件的概述<br>
 
@class<br>
提供類的有關信息，用在構造函數的文檔中<br>
 
@constructor<br>
明確一個函數是某個類的構造函數<br>
 
@type<br>
指定函數的返回類型<br>
 
@extends<br>
指示一個類派生了另一個類。JSDoc通常自己就可以檢測出這種信息，不過，在某些情況下則必須使用這個標記<br>
 

續(xù)表<br>

命 令 名<br>
描    述<br>
 
@private<br>
指示一個類或函數是私有的。私有類和函數不會出現在HTML文檔中，除非運行JSDoc時提供了--private命令行選項<br>
 
@final<br>
指示一個值是常量值。要記住JavaScript無法真正保證一個值是常量<br>
 
@ignore<br>
JSDoc忽略有這個標記的函數<br>
 

JSDoc發(fā)布包中包括一個名為test.js的文件，這是一個很好的參考例子，可以從中了解如何使用JSDoc。你應該記得，第一次測試JSDoc安裝是否成功時就是根據這個文件來創(chuàng)建文檔文件的。如果對如何使用JSDoc標記還有疑問，可以參考這個文件。<br>

代碼清單5-1是一個小示例，展示了JSDoc的用法。jsDocExample.js定義了兩個類：Person和Employee。Person類有一個屬性name，還有一個方法getName。Employee類繼承自Person類，并增加了title和salary屬性，另外還增加了一個方法getDescription。<br>

代碼清單5-1  <br>
 jsDocExample.js<br>
 /**<br>
 * @fileoverview This file is an example of how JSDoc can be used to document<br>
 * JavaScript. <br>
 *<br>
 * @author Ryan Asleson<br>
 * @version 1.0<br>
 */<br>
 /**<br>
 * Construct a new Person class.<br>
 * @class This class represents an instance of a Person.<br>
 * @constructor<br>
 * @param {String} name The name of the Person.<br>
 * @return A new instance of a Person.<br>
 */<br>
 function Person(name) {<br>
    /**<br>
     * The Person's name<br>
     * @type String<br>
    */<br>
    this.name = name;<br>
    /**<br>
     * Return the Person's name. This function is assigned in the class<br>
     * constructor rather than using the prototype keyword.<br>
     * @returns The Person's name<br>
     * @type String<br>
    */<br>
    this.getName = function() {<br>
        return name;<br>
    }<br>
 }<br>
 /**<br>
 * Construct a new Employee class.<br>
 * @extends Person<br>
 * @class This class represents an instance of an Employee.<br>
 * @constructor<br>
 * @return A new instance of a Person.<br>
 */<br>
 function Employee(name, title, salary) {<br>
    this.name = name;<br>
    /**<br>
     * The Employee's title<br>
     * @type String<br>
    */<br>
    this.title = title;<br>
   /**<br>
     * The Employee's salary<br>
     * @type int<br>
    */<br>
    this.salary = salary;<br>
 }<br>
 /* Employee extends Person */<br>
 Employee.prototype = new Person();<br>
 /**<br>
 * An example of function assignment using the prototype keyword.<br>
 * This method returns a String representation of the Employee's data.<br>
 * @returns The Employee's name, title, and salary<br>
 * @type String<br>
 */<br>
 Employee.prototype.getDescription = function() {<br>
    return this.name + " - "<br>
        + this.title + " - "<br>
        + "$" + this.salary;<br>
 }<br>

雖然不像JSDoc發(fā)布包中的test.js文件那么完備，這個示例同樣很好地展示了JSDoc最常見的用法（見圖5-1）。@fileoverview 標記提供了jsDocExample.js的概述。@class標記描述了兩個類，@constructor標記將適當的函數標記為對象的構造函數。@param標記描述了函數的輸入參數，@returns和@type標記描述了函數的返回值和返回類型。這些標記是你最有可能用到的，而且對于瀏覽文檔的其他開發(fā)人員，這些標記也最有用。<br>
[[Image:image001.jpg]]
[[category:Ajax]]