編輯“Ajax- 使用JSDoc建立JavaScript代碼的文檔”

<span style="text-align:center; border:1px solid #000; float:right; padding:6px;"><strong>導(dǎo)航:</strong> [[Ajax學(xué)習(xí)教程#Ajax學(xué)習(xí)教程|上一頁]] | {{template:開發(fā)語言導(dǎo)航}}</span>
<div style="clear:both;"></div>
作為一名有經(jīng)驗的Web應(yīng)用開發(fā)人員，你也許可以熟練地應(yīng)用某種服務(wù)器端技術(shù)（或者，應(yīng)用多種服務(wù)器端技術(shù)）來構(gòu)建Web應(yīng)用。我們已經(jīng)看到，在過去幾年中，服務(wù)器端技術(shù)有了長足的發(fā)展，服務(wù)器端軟件開發(fā)越來越容易，也越來越健壯，相比之下，客戶端技術(shù)基本上被拋在了一邊。Ajax技術(shù)的橫空出世使這種狀況有所改觀，因為開發(fā)人員現(xiàn)在有了一個更豐富的客戶端工具箱，有大量工具可以使用。你可能不習(xí)慣使用大量的HTML、JavaScript和CSS，但是如果要實現(xiàn)Ajax技術(shù)，你就必須這么做。本章將介紹的工具和技術(shù)會使得開發(fā)Ajax應(yīng)用更為容易。本章不是深入全面的教程，只能作為這些有用工具和技術(shù)的快速入門。 <br>


== 使用JSDoc建立JavaScript代碼的文檔 ==


像其他的許多編程語言一樣，在一般的軟件開發(fā)人員看來，JavaScript也有一個基本的缺陷：編寫（或者重新編寫）一個功能通常相對容易，但是要閱讀現(xiàn)有的代碼并明確它是如何工作的，就不那么輕松了。編寫代碼時可以適當(dāng)?shù)卦黾幼⑨專@樣當(dāng)其他開發(fā)人員要理解代碼如何工作，特別是要修改代碼的功能時，就能減輕他們的負(fù)擔(dān)，節(jié)省他們的時間和精力。<br>

Java語言引入了一個工具，名為javadoc。這個工具可以根據(jù)源代碼中的文檔注釋以HTML格式生成API文檔。所生成的HTML文檔在任何Web瀏覽器上都能閱讀，而且由于它是以HTML格式生成的，所以可以在線發(fā)布，這樣開發(fā)人員就能很容易地訪問這些文檔。以一種可以輕松瀏覽的格式來提供API文檔，這種方法使得開發(fā)人員不必仔細(xì)地查看源代碼才能了解某個類或方法會有怎樣的行為，以及該如何使用。<br>

JSDoc是面向JavaScript的一個類似的工具（jsdoc.sourceforge.net）。JSDoc是一個開源工具，是采用GPL（GNU Public License）協(xié)議發(fā)布的。JSDoc用Perl編寫，這意味著Windows用戶必須安裝一個Perl運(yùn)行時環(huán)境。（而對于大多數(shù)Linux和Unix操作系統(tǒng)，Perl是其中的一個標(biāo)準(zhǔn)部分）。<br>


== 安裝 ==


要使用JSDoc，Windows用戶必須安裝一個Perl環(huán)境，如ActivePerl（www.activeperl. com）。還必須安裝一個非標(biāo)準(zhǔn)的Perl模塊，名為HTML::Template（www.cpan.org）。JSDoc項目網(wǎng)頁提供了有關(guān)說明，如果需要幫助可以參考。 <br>

JSDoc發(fā)布為一個壓縮的tarball。要安裝JSDoc，你只需從JSDoc項目網(wǎng)頁下載tarball，把它解開到指定的目錄，進(jìn)入JSDoc目錄，輸入以下命令，就能測試JSDoc了：<br>

perl jsdoc.pl test.js<br>

JSDoc將所得到的HTML文件保存到名為js_docs_out的目錄。打開這個文件夾中的index.html文件，就可以瀏覽根據(jù)test.js文件生成的文檔。<br>

== 用法 ==


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

JSDoc命令屬性<br>

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

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

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

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

續(xù)表<br>

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

JSDoc發(fā)布包中包括一個名為test.js的文件，這是一個很好的參考例子，可以從中了解如何使用JSDoc。你應(yīng)該記得，第一次測試JSDoc安裝是否成功時就是根據(jù)這個文件來創(chuàng)建文檔文件的。如果對如何使用JSDoc標(biāo)記還有疑問，可以參考這個文件。<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 標(biāo)記提供了jsDocExample.js的概述。@class標(biāo)記描述了兩個類，@constructor標(biāo)記將適當(dāng)?shù)暮瘮?shù)標(biāo)記為對象的構(gòu)造函數(shù)。@param標(biāo)記描述了函數(shù)的輸入?yún)?shù)，@returns和@type標(biāo)記描述了函數(shù)的返回值和返回類型。這些標(biāo)記是你最有可能用到的，而且對于瀏覽文檔的其他開發(fā)人員，這些標(biāo)記也最有用。<br>
[[Image:image001.jpg]]
[[category:Ajax]]