使用jsdoc建立javascript文档

刚刚使用jsdoc实验/学习创建了javascript文档，这里写一点基本的记录。

 

jsdoc的sourceforge项目地址：http://jsdoc.sourceforge.net/

 

安装和使用

 

安装应该说比较简单，可以参考用JSDoc建立有益的JavaScript相关文档。为防止链接失效，这里拷贝一个文本备份：

 

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

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

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

成功安装ActivePerl后，接下来就要下载和解压JSDoc。这时，你可能会在一个DOS窗口中运行JSDoc，但如果你这样做，它可能无法运行。这是因为你缺少一个Perl软件包，如图B所示[图略](注：错误提示为Can't locate HTML/Template.pm in @INC ..... )。幸运的是，你可以在同一个窗口中输入ppm调用Perl软件包管理器，如图C所示[图略]。

使用Perl软件包管理器，你就可以安装缺少的HTML-模板软件包，如图D所示。[图略](注：点击工具栏View All packages[Ctr+1]按钮，在搜索框输入HTML-Template，选中列表中的HTML-Template项，如果它前面的图标是灰色的，右键并点击出现的唯一菜单项 Install HTML-Template安装，也可以标记然后安装)
(又注：网上有"在Dos窗口输入ppm命令，然后
PPM> install HTML-Template
PPM> quit "的做法，不过我下载的1.10.2版输入ppm就会弹出软件包管理器，命令行不可输入)

使用JSDoc

表中列出了一些你可以在JavaScript文档中使用的标签。

标签	描述
@addon	把一个函数标记为另一个函数的扩张，另一个函数的定义不在源文件中。
@argument	用大括号中的自变量类型描述一个自变量。
@author	函数/类作者的姓名。
@base	如果类是继承得来，定义提供的类名称。
@class	用来给一个类提供描述，不能用于构造器的文档中。
@constructor	描述一个类的构造器。
@deprecated	表示函数/类已被忽略。
@exception	描述函数/类产生的一个错误。
@exec
@extends	表示派生出当前类的另一个类。
@fileoverview	表示文档块将用于描述当前文件。这个标签应该放在其它任何标签之前。
@final	指出函数/类。
@ignore	让JSDoc忽视随后的代码。
@link	类似于@link标签，用于连接许多其它页面。
@member	定义随后的函数为提供的类名称的一个成员。
@param	用大括号中的参数类型描述一个参数。
@private	表示函数/类为私有，不应包含在生成的文档中。
@requires	表示需要另一个函数/类。
@return	描述一个函数的返回值。
@returns	描述一个函数的返回值。
@see	连接到另一个函数/类。
@throws	描述函数/类可能产生的错误。
@type	指定函数/成员的返回类型。
@version	函数/类的版本号。

除上面提供的信息外，在JSDoc.pl命令后增加-h或-help选项，就会显示在生成文档时可以使用的选项列表。图G显示的是使用帮助选项的结果。

命令行进入JsDoc根目录，输入命令：
> perl jsdoc.pl test.js tes2.js
默认安装perl会设置将perl安装路径放入系统环境变量，这样你可以在任意路径中使用perl命令。如果你想在任意目录找到jsdoc.pl，可以将jsdoc安装目录设置到系统环境变量中。可以批量为javascript源代码生成文档。

 

乱码问题

默认情况下生成中文文档会出现乱码，如果你查看文档源代码就会发现，源代码本没有乱码，你只需要在JSDoc文档模板(根目录下所有的tmpl文件，有的版本可能在JSDoc子目录下)头部加上META标记并重新生成文档即可。
<meta http-equiv="content-type" content="text/html; charset=gb2312" />
其中粗体gb2312可以换成Big5，UTF-8之类，请设置为与javascript源代码文件编码格式相同。
see http://caterpillar.onlyfun.net/GossipCN/AjaxGossip/JSDocBig5.html

 

集成到Editplus

点击菜单栏工具，选择配置用户工具，

菜单文本：jsdoc (可随意)

命令：perl                              (如果没有设置perl的环境变量，请指定到%PERL_HOME%\bin\perl.exe )

参数：jsdoc.pl $(FileName)    (如没有设置jsdoc的环境变量，使用%JSDOC_HOME%\jsdoc.pl $(FileName) )
初始目录：$(FileDir)

 

其他设置按照个人习惯酌情设置。