作为一名有经验的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通常自己就可以检测出这种信息，不过，在某些情况下则必须使用这个标记 |
本文作者: