Java核心技术第4章(9)

4.9 文档注释

JDK包含一个很有用的工具,叫做javadoc,它可以由源文件生成一个HTML文档.
如果将文档存入一个独立的文件中,就有可能会随着时间的推移,出现代码和注释不一致的问题.然而,由于文档注释与源代码在同一个文件中,修改源代码的同时,重新运行javadoc就可以轻而易举地保持两者的一致性.

4.9.1 注释的插入

javadoc实用程序(utility)从下面几个特性中抽取信息:
包
公有类与接口
公有的和受保护的构造器及方法
公有的和受保护的域
应该为上面几个部分编写注释.注释应该设置在所描述特性的前面.
每个/** ... */ 文档注释在标记之后紧跟着*格式文本.标记由@开始,如@author或@param .

4.9.2 类注释

类注释必须在 import 语句之后,类定义之前
下面是一个类注释的例子:

/** * A <code>Card</code> object represents a playing card
 */
public class Card
{
    ...
}

4.9.3 方法注释

每一个方法注释必须放在所描述的方法之前.除了通用标记之外,还可以使用下面的标记:
@param 变量描述
这个标记将对当前方法的"param"部分添加一个条目,一个方法的所有@param 标记必须放在一起.
@return 描述
这个标记将对当前方法添加"return"部分.
@throws 类描述
这个标记将添加一个注释,用于表示这个方法有可能抛出异常
下面是一个方法注释的示例:

/** * Raises the salary of an employee
 * @param byPercent the percentage by which to raise the salary
 * @return the amount of the raise
 */
public double raiseSalary(double byPercent)
{
    double raise = salary * byPercent / 100;
    salary += raise;
    return raise;
}

4.9.4 域注释

只需要对公有域(通常指的是静态常量)建立文档.例如:

/** * The "Hearts" card suit
 */
public static final int HEARTS = 1;

4.9.5 通用注释

用在类文档的注释中.

4.9.6 包与概述注释

可以直接将类,方法和变量的注释放置在java源文件中.

4.9.7 注释的抽取

这里,假设HTML文件将被存放在目录docDirectory下.执行以下步骤:
1.切换到包含想要生成文档的源文件目录.
2.如果是个包,应该运行命令:

javadoc -d docDirectory nameofPackage

如果是类,则运行命令:

javadoc -d docDirectory nameofClass(Name.java)

如果省略了-d docDirectory选项,那么HTML文件就会被提取到当前目录下.

秒客网