用JSDoc建立有益的JavaScript相关文档

不管因为什么原因，不给一个应用程序建立文档都不是一件好事，即使建立文档的工作一般令人厌烦。在给客户端JavaScript建立文档时尤其如此；与服务器端技术相比，客户端JavaScript通常被人们认为是前者的一个丑陋的继子。有趣的是，JavaScript文档问题的解决办法却来自一个非常相似的服务器端技术——Java。

有一个非常简洁的工具叫做Javadoc，可帮助Java开发者生成文档。这个工具还有一个JavaScript版本——JSDoc，它可用于开发HTML文档，不仅帮助你给代码建立文档，而且有助于预防一些问题，如几个函数或对象基本上实现相同的功能，以及缺乏一般性的库知识。本教程将为你说明如何安装和使用JSDoc，以给JavaScript创建文档。

安装JSDoc
遗憾的是，安装JSDoc并不十分简单。这主要是因为它是用Perl编写的，因此除非你已经安装了Perl，否则就需要一两个额外的步骤。由于我最近在笔记本电脑上安装了Windows XP Pro，我自己就经历过这些额外的步骤。首先我必须下载和安装ActivePerl，它是一个msi文件。图A显示了一部分安装过程。

图A

安装ActivePerl

成功安装ActivePerl后，接下来就要下载和解压JSDoc。这时，你可能会在一个DOS窗口中运行JSDoc，但如果你这样做，它可能无法运行。这是因为你缺少一个Perl软件包，如图B所示。幸运的是，你可以在同一个窗口中输入ppm调用Perl软件包管理器，如图C所示。

图B

DOS窗口

图C
Pe
Perl软件包管理器

使用Perl软件包管理器，你就可以安装缺少的HTML-模板软件包，如图D所示。

图D

安装一个Perl软件包