Ajax基礎教程（5）- 5.1 使用JSDoc建立JavaScript代碼的文檔

作為一名有經驗的Web應用開發人員，你也許可以熟練地應用某種伺服器端技術（或者，應用多種伺服器端技術）來構建Web應用。我們已經看到，在過去幾年中，伺服器端技術有了長足的發展，伺服器端軟體開發越來越容易，也越來越健壯，相比之下，用戶端技術基本上被拋在了一邊。Ajax技術的橫空出世使這種狀況有所改觀，因為開發人員現在有了一個更豐富的用戶端工具箱，有大量工具可以使用。你可能不習慣使用大量的HTML、JavaScript和CSS，但是如果要實現Ajax技術，你就必須這麼做。本章將介紹的工具和技術會使得開發Ajax應用更為容易。本章不是深入全面的教程，只能作為這些有用工具和技術的快速入門。

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

像其他的許多程式設計語言一樣，在一般的軟體開發人員看來，JavaScript也有一個基本的缺陷：編寫（或者重新編寫）一個功能通常相對容易，但是要閱讀現有的代碼並明確它是如何工作的，就不那麼輕鬆了。編寫代碼時可以適當地增加註釋，這樣當其他開發人員要理解代碼如何工作，特別是要修改代碼的功能時，就能減輕他們的負擔，節省他們的時間和精力。

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

JSDoc是面向JavaScript的一個類似的工具（jsdoc.sourceforge.net）。JSDoc是一個開源工具，是採用GPL（GNU Public License）協議發布的。JSDoc用Perl編寫，這意味著Windows使用者必須安裝一個Perl運行時環境。（而對於大多數Linux和Unix作業系統，Perl是其中的一個標準部分）。

5.1.1　安裝

要使用JSDoc，Windows使用者必須安裝一個Perl環境，如ActivePerl（www.activeperl. com）。還必須安裝一個非標準的Perl模組，名為HTML::Template（www.cpan.org）。JSDoc項目網頁提供了有關說明，如果需要協助可以參考。

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

perl jsdoc.pl test.js

JSDoc將所得到的HTML檔案儲存到名為js_docs_out的目錄。開啟這個檔案夾中的index.html檔案，就可以瀏覽根據test.js檔案產生的文檔。

5.1.2　用法

既然對JSDoc已經有所瞭解，你可能想知道如何使用JSDoc來為你的JavaScript代碼產生文檔。表5-1列出了可以建立HTML文檔的一些特殊JSDoc標記。這些標記對於曾在Java代碼中編寫過javadoc注釋的人員並不陌生。包含在產生文檔中的每個註解區塊都必須以/**開頭，並以*/結束。

表5-1　JSDoc命令屬性

命 令 名	描　　述
@param @argument	指定參數名和說明來描述一個函數參數
@return @returns	描述函數的傳回值
@author	指示代碼的作者
@deprecated	指示一個函數已經廢棄，而且在將來的代碼版本中將徹底刪除。要避免使用這段代碼
@see	建立一個HTML連結，指向指定類的描述
@version	指定發布版本
@requires	建立一個HTML連結，指向這個類所需的指定類
@throws @exception	描述函數可能拋出的異常的類型
{@link}	建立一個HTML連結，指向指定的類。這與@see很類似，但{@link}能嵌在注釋文本中
@fileoverview	這是一個特殊的標記。如果在檔案的第一個文檔塊中使用這個標記，則指定該文檔塊的餘下部分將用來提供這個檔案的概述
@class	提供類的有關資訊，用在建構函式的文檔中
@constructor	明確一個函數是某個類的建構函式
@type	指定函數的傳回型別
@extends	指示一個類派生了另一個類。JSDoc通常自己就可以檢測出這種資訊，不過，在某些情況下則必須使用這個標記