| 5.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}能嵌在注释文本中 |
| @fileoverview |
这是一个特殊的标记。如果在文件的第一个文档块中使用这个标记，则指定该文档块的余下部分将用来提供这个文件的概述 |
| @class |
提供类的有关信息，用在构造函数的文档中 |
| @constructor |
明确一个函数是某个类的构造函数 |
| @type |
指定函数的返回类型 |
| @extends |
指示一个类派生了另一个类。JSDoc通常自己就可以检测出这种信息，不过，在某些情况下则必须使用这个标记 |
续表
| 命 令
名 |
描 述 |
| @private |
指示一个类或函数是私有的。私有类和函数不会出现在HTML文档中，除非运行JSDoc时提供了--private命令行选项 |
| @final |
指示一个值是常量值。要记住JavaScript无法真正保证一个值是常量 |
| @ignore |
JSDoc忽略有这个标记的函数 |
JSDoc发布包中包括一个名为test.js的文件，这是一个很好的参考例子，可以从中了解如何使用JSDoc。你应该记得，第一次测试JSDoc安装是否成功时就是根据这个文件来创建文档文件的。如果对如何使用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标记描述了函数的返回值和返回类型。这些标记是你最有可能用到的，而且对于浏览文档的其他开发人员，这些标记也最有用。
图5-1 JSDoc根据jsDocExample.js文件生成的文档
上一页 首页
下一页 |