5.1 使用JSDoc建立JavaScript代码的文档--Ajax基础教程 -UML软件工程组织-火龙果软件

作为一名有经验的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是其中的一个标准部分）。