js编码规范, JSDoc建立JavaScript代码的文档

像其他的许多编程语言一样，在一般的软件开发人员看来，JavaScript也有一个基本的缺陷：编写（或者重新编写）一个功能通常相对容易，但是要阅读现有的代码，并明确它是如何工作的, 就不那么轻松了。编写代码时可以适当地增加注释，这样当其他开发人员要理解代码如何工作，特别是要修改代码的功能时，就能减轻他们的负担，节省他们的时间和精力。
Java语言引入了一个工具，名为javadoc。这个工具可以根据源代码中的文档注释以HTML格式生成API文档。所生成的HTML文档在任何Web浏览器上都能阅读，而且由于它是以HTML格式生成的，所以可以在线发布，这样开发人员就能很容易地访问这些文档。要以一种可以轻松浏览的格式来提供API文档，这样开发人员就不必仔细地查看源代码才能了解某个类或方法会有怎样的行为，以及该如何使用。
JSDoc则是面向JavaScript的一个类似的工具（jsdoc.sourceforge.net）。JSDoc是一个开源工具，得到了GNU Public License（GPL）的许可。JSDoc用Perl编写，这意味着Windows用户必须先安装一个Perl运行时环境。（而对于大多数Linux和Unix操作系统，Perl都会作为其中的一个标准部分。）

1.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文件生成的文档。
1.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}能嵌在注释文本中。
@author 指示代码的作者。（译者注：这个标记前面已经出现过，建议去掉）
@fileoverview 这是一个特殊的标记，如果在文件的第一个文档块中使用这个标记，则指定该文档块的余下部分将用来提供文件的一个概述。
@class 提供类的有关信息，用在构造函数的文档中。
@constructor 明确一个函数是某个类的构造函数。
@type 指定函数的返回类型。
@extends 指示一个类派生了另一个类。通常JSDoc自己就可以检测出这种信息，不过，在某些情况下则必须使用这个标记。
@private 指示一个类或函数是私有的。私有类和函数不会出现在HTML文档中，除非运行JSDoc时提供了—private命令行选项。
@final 指示一个值是常量值。要记住JavaScript无法真正保证一个值是常量。
@ignore JSDoc会忽略有这个标记的函数。


JSDoc发布包中包括一个名为test.js的文件，这是一个很好的参考例子，可以从中了解如何使用JSDoc。应该记得，第一次测试JSDoc安装是否成功时就是根据这个文件来创建文档文件（译者注：原文称“这就是第一次测试JSDoc安装是否成功时创建的文档文件”，这种理解有误，test.js显然不是文档文件，所得到的文档文件应当是js_docs_out的目录下的index.html）。如果对如何使用JSDoc标记还有疑问，可以参考这个文件。
代码清单5-1是一个小例子，这里展示了JSDoc的用法。jsDocExample.js定义了两个类：Person和Employee。Person类有一个属性name，还有一个方法getName。Employee类继承自Person，并增加了title和salary属性，另外还增加了一个方法getDescription。
代码清单5-1. jsDocExample.js
/**
* @fileoverview This file is an example of how JSDoc can be used to document
* JavaScript.
*
* @author Ryan Asleson
* @version 1.0
*/
/**
* Construct a new Person class.
* @class This class represents an instance of a Person.
* @constructor
* @param {String} name The name of the Person.
* @return A new instance of a Person.
*/
function Person(name) {
/**
* The Person's name
* @type String
*/
this.name = name;

/**
* Return the Person's name. This function is assigned in the class
* constructor rather than using the prototype keyword.
* @returns The Person's name
* @type String
*/
this.getName = function() {
return name;
}
}
/**
* Construct a new Employee class.
* @extends Person
* @class This class represents an instance of an Employee.
* @constructor
* @return A new instance of a Person.
*/
function Employee(name, title, salary) {
this.name = name;
/**
* The Employee's title
* @type String
*/
this.title = title;
/**
* The Employee's salary
* @type int
*/
this.salary = salary;
}
/* Employee extends Person */
Employee.prototype = new Person();
/**
* An example of function assignment using the prototype keyword.
* This method returns a String representation of the Employee's data.
* @returns The Employee's name, title, and salary
* @type String
*/
Employee.prototype.getDescription = function() {
return this.name + " - "
+ this.title + " - "
+ "$" + this.salary;
}

虽然不像JSDoc发布包中的test.js文件那么完备，这个例子同样很好地展示了JSDoc最常见的用法（见图5-1）。 @fileoverview 标记提供了jsDocExample.js的一个概述。@class标记描述了两个类，@constructor标记将适当的函数标记为对象的构造函数。@param 标记描述了一个函数的输入参数，@returns和@type标记描述了函数的返回值。这些标记是你最有可能用到的，而且对于浏览文档的其他开发人员，这些标记也最有用。