Question

所有 javadoc 命令都只能出现于“/**”注释中。但和平常一样，注释结束于一个“*/”。主要通过两种方式来使用 javadoc：嵌入的 HTML，或使用“文档标记”。其中，“文档标记”（Doc tags）是一些以“@”开头的命令，置于注释行的起始处（但前导的“*”会被忽略）。

有三种类型的注释文档，它们对应于位于注释后面的元素：类、变量或者方法。也就是说，一个类注释正好位于一个类定义之前；变量注释正好位于变量定义之前；而一个方法定义正好位于一个方法定义的前面。如下面这个简单的例子所示：

/** 一个类注释 */

public class docTest {

/** 一个变量注释 */

public int i;

/** 一个方法注释 */

public void f() {}

}

注意 javadoc 只能为 public（公共）和 protected（受保护）成员处理注释文档。“private”（私有）和“友好”（详见 5 章）成员的注释会被忽略，我们看不到任何输出（也可以用-private 标记包括 private 成员）。这样做是有道理的，因为只有 public 和 protected 成员才可在文件之外使用，这是客户程序员的希望。然而，所有类注释都会包含到输出结果里。

上述代码的输出是一个 HTML 文件，它与其他 Java 文档具有相同的标准格式。因此，用户会非常熟悉这种格式，可在您设计的类中方便地“漫游”。设计程序时，请务必考虑输入上述代码，用 javadoc 处理一下，观看最终 HTML 文件的效果如何。