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文件就会被提取到当前目录下.