Ajax- 使用JSDoc建立JavaScript代碼的文檔

導(dǎo)航: 上一頁 | ASP | PHP | JSP | HTML | CSS | XHTML | aJAX | Ruby | JAVA | XML | Python | ColdFusion

作為一名有經(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ù)的快速入門。

使用JSDoc建立JavaScript代碼的文檔

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

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

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

安裝

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

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

perl jsdoc.pl test.js

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

用法

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

JSDoc命令屬性

命 令 名
描 述

@param

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

@return

@returns
描述函數(shù)的返回值

@author
指示代碼的作者

@deprecated

指示一個函數(shù)已經(jīng)廢棄，而且在將來的代碼版本中將徹底刪除。要避免使用這段代碼

@see
創(chuàng)建一個HTML鏈接，指向指定類的描述

@version
指定發(fā)布版本

@requires
創(chuàng)建一個HTML鏈接，指向這個類所需的指定類

@throws

@exception
描述函數(shù)可能拋出的異常的類型

{@link}
創(chuàng)建一個HTML鏈接，指向指定的類。這與@see很類似，但{@link}能嵌在注釋文本中

@fileoverview
這是一個特殊的標(biāo)記。如果在文件的第一個文檔塊中使用這個標(biāo)記，則指定該文檔塊的余下部分將用來提供這個文件的概述

@class
提供類的有關(guān)信息，用在構(gòu)造函數(shù)的文檔中

@constructor
明確一個函數(shù)是某個類的構(gòu)造函數(shù)

@type
指定函數(shù)的返回類型

@extends
指示一個類派生了另一個類。JSDoc通常自己就可以檢測出這種信息，不過，在某些情況下則必須使用這個標(biāo)記

續(xù)表

命 令 名
描 述

@private
指示一個類或函數(shù)是私有的。私有類和函數(shù)不會出現(xiàn)在HTML文檔中，除非運行JSDoc時提供了--private命令行選項

@final
指示一個值是常量值。要記住JavaScript無法真正保證一個值是常量

@ignore
JSDoc忽略有這個標(biāo)記的函數(shù)

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

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

代碼清單5-1

jsDocExample.js

/**

* @fileoverview This file is an example of how JSDoc can be used to document

* JavaScript. 

*

* @author Ryan Asleson

* @version 1.0

*/

/**

* 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;

   /**

    * Return the Person's name. This function is assigned in the class

    * constructor rather than using the prototype keyword.

    * @returns The Person's name

    * @type String

   */

   this.getName = function() {

       return name;

   }

}

/**

* Construct a new Employee class.

* @extends Person

* @class This class represents an instance of an Employee.

* @constructor

* @return A new instance of a Person.

*/

function Employee(name, title, salary) {

   this.name = name;

   /**

    * The Employee's title

    * @type String

   */

   this.title = title;

  /**

    * The Employee's salary

    * @type int

   */

   this.salary = salary;

}

/* Employee extends Person */

Employee.prototype = new Person();

/**

* An example of function assignment using the prototype keyword.

* This method returns a String representation of the Employee's data.

* @returns The Employee's name, title, and salary

* @type String

*/

Employee.prototype.getDescription = function() {

   return this.name + " - "

       + this.title + " - "

       + "$" + this.salary;

}

雖然不像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)記也最有用。