Javascript工具 - 使用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通常自己就可以檢測出這種資訊，不過，在某些情況下則必須使用這個标記

　　續表

@private

訓示一個類或函數是私有的。私有類和函數不會出現在HTML文檔中，除非運作JSDoc時提供了--private指令行選項

@final

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

@ignore

JSDoc忽略有這個标記的函數

　　JSDoc釋出包中包括一個名為test.js的檔案，這是一個很好的參考例子，可以從中了解如何使用JSDoc。你應該記得，第一次測試JSDoc安裝是否成功時就是根據這個檔案來建立文檔檔案的。如果對如何使用JSDoc标記還有疑問，可以參考這個檔案。

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

　　代碼清單5-1 jsDocExample.js

<code>　　/** * @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; }</code>

　　雖然不像JSDoc釋出包中的test.js檔案那麼完備，這個示例同樣很好地展示了JSDoc最常見的用法（見圖5-1）。@fileoverview 标記提供了jsDocExample.js的概述。@class标記描述了兩個類，@constructor标記将适當的函數标記為對象的構造函數。@param标記描述了函數的輸入參數，@returns和@type标記描述了函數的傳回值和傳回類型。這些标記是你最有可能用到的，而且對于浏覽文檔的其他開發人員，這些标記也最有用。

　　圖5-1　JSDoc根據jsDocExample.js檔案生成的文檔