小时侯，我家里很穷，没钱买自行车，我只好每天打的上学。初中的时候，因为我成绩太突出，学校领导留我多读了两年。初中毕业后，高中的校长觉得我很有前途，就多收了我2万5。高三的时候，班主任认为我已经有独立生存的能力，于是让我退了学。
不管因为什么原因，不给一个应用程序建立文档都不是一件好事，即使建立文档的工作一般令人厌烦。在给客户端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
Javascript 数据类型分为值类型和引用类型，其中值类型包括字符串实体（例如："string" ），数值实体（例如：100 ）和布尔值实体（如：true ）。而其他的复杂类型都属于引用类型，例如日期型（ new Date() ），正则表达式（/a/gi, new RegExp("a", "gi") ）数组（ [1,2,3], new Array() ）函数（function(){}, new Function() ）和对象（{a:"a", b:100}, new Object() ）。这些都是Javascript 固有的数据类型，而用户自定义类型都属于引用类型（如：var Person = function(name){this.name=name;}; ），它们都只能使用new 关键字实例化为具体对象（new Person("hotoo") ）。
为了理解Javascript 对象的类型，我们来看一些如下代码：
// test instanceof and typeof:
var instStr = ['"string"', '100' , 'true', '/a/g' , '[1,2,3]' , 'function(){}', '{}', 'null', 'undefined' ];
var inst = ["string", 100, true, /a/g, [1 ,2,3 ], function (){}, {}, null, undefined];
var ObjsStr = ["String", "Number" , "Boolean", "RegExp" , "Array", "Function", "Date" , "Object"];
var Objs = [String, Number , Boolean, RegExp, Array, Function, Date, Object];
jsoutInst ( "instanceof" , ObjsStr, Objs , instStr, inst);
function jsoutInst (methodName, tsStr , ts , osStr, os ){
document.write ("<table border='1'><tr>" );
document.write ("<td><strong>" +methodName+ "</strong></td>" );
for (var i= 0; i< tsStr. length; i++){
document.write ("<td>" +tsStr[i ]+"</td>" );
}
document.write ("</tr>" );
for (var i= 0; i< os. length; i++){
document.write ("<tr><td>" +osStr[i ]+"</td>" );
for (var j= 0; j< ts. length; j ++){
document.write ("<td>" +(os[i ] instanceof ts[j]? "<strong>true</strong>" :"false")+"</td>" );
}
document.write ("</tr>" );
}
document.write ("</table><br />" );
}
var typesStr = ["string", "number" , "boolean", "array" , "function", "date", "object" , "undefined"];
jsoutType ( "typeof" , typesStr, instStr , inst);
function jsoutType (methodName, tsStr , osStr , os){
document.write ("<table border='1'><tr>" );
document.write ("<td><strong>" +methodName+ "</strong></td>" );
for (var i= 0; i< tsStr. length; i++){
document.write ("<td>" +tsStr[i ]+"</td>" );
}
document.write ("</tr>" );
for (var i= 0; i< os. length; i++){
document.write ("<tr><td>" +osStr[i ]+"</td>" );
for (var j= 0; j< tsStr. length; j ++){
document.write ("<td>" +(typeof os[ i] == tsStr[ j]?"<strong>true</strong>" :"false" )+"</td>" );
}
document.write ("</tr>" );
}
document.write ("</table><br />" );
}
上面的代码很简单，第一个函数判断对象实例是否是某个类的实例（instanceof ），第二个函数对比对象实例是否与某类型（typeof ）相等，他们将输出两个表格，我们来对比一下（为了方便阅读，这里将说明插在相应表格下。 ）。
instanceof String Number Boolean RegExp Array Function Date Object "string" false false false false false false false false 100 false false false false false false false false true false false false false false false false false /a/g false false false true false false false true [1,2,3] false false false false true false false true function(){} false false false false false true false true {} false false false false false false false true null false false false false false false false false undefined false false false false false false false false
通过（instanceof ）这个表格可以看出，值类型（ "string", 100, true 等）不是任何对象的实体（instance ），而引用类型（/a/g, [1,2,3], function(){} 和 {} ）既是本身类型的实体，又是其父类型的实体（所有类型都继承自Object 类型）。
所有通过引用类型（包括值类型的wrapper 类String, Number 和 Boolean ）new 出来的对象，都是其对应类和其父类（这里是Object ）的实例。
虽然值类型不是其对应wrapper 类的实例，但是值类型却可以直接使用其wrapper 类的属性和方法，就如同值类型是其 wrapper 类的实例一样。例如："ABC".toLowerCase() 。
| typeof | string | number | boolean | array | function | date | object | undefined |
| "string" | true | false | false | false | false | false | false | false |
| 100 | false | true | false | false | false | false | false | false |
| true | false | false | true | false | false | false | false | false |
| /a/g | false | false | false | false | false | false | true | false |
| [1,2,3] | false | false | false | false | false | false | true | false |
| function(){} | false | false | false | false | true | false | false | false |
| {} | false | false | false | false | false | false | true | false |
| null | false | false | false | false | false | false | true | false |
| undefined | false | false | false | false | false | false | false | true |
