JAVA注释

一、注释

1.1 javadoc

        JDK 包含一个很有用的工具，叫做javadoc, 它可以由源文件生成一个 HTML 文档。
        如果在源代码中添加以专用的定界符 /**开始的注释， 那么可以很容易地生成一个看上去具有专业水准的文档。这是一种很好的方式，因为这种方式可以将代码与注释保存在一个地方。如果将文档存人一个独立的文件中， 就有可能会随着时间的推移， 出现代码和注释不一致的问题。然而，由于文档注释与源代码在同一个文件中，在修改源代码的同时， 重新运行 javadoc 就可以轻而易举地保持两者的一致性。
        javadoc 实用程序（utility) 从下面几个特性中抽取信息：

• 包
• 公有类与接口
• 公有的和受保护的构造器及方法
• 公有的和受保护的域

1.2 类注释

        类注释必须放在 import 语句之后，类定义之前。

1.3 方法注释

        每一个方法注释必须放在所描述的方法之前。除了通用标记之外， 还可以使用下面的标记：

• @param 变量描述
  这个标记将对当前方法的“ param” （参数）部分添加一个条目。这个描述可以占据多行， 并可以使用 HTML 标记。一个方法的所有 @param 标记必须放在一起。
• @return 描述
  这个标记将对当前方法添加“ return” （返回）部分。这个描述可以跨越多行， 并可以使用 HTML 标记。
• @throws 类描述
  这个标记将添加一个注释， 用于表示这个方法有可能抛出异常。

1.4 注释

只需要对公有域（通常指的是静态常量）建立文档

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

1.5 通用注释

• @author 姓名
  这个标记将产生一个 “author” (作者）条目。可以使用多个 @author 标记，每个 @author 标记对应一个作者
• @version 版本
  这个标记将产生一个“ version”（版本）条目。这里的文本可以是对当前版本的任何描述。

下面的标记可以用于所有的文档注释中。

• @since 文本
  这个标记将产生一个“ since” （始于）条目。这里的 text 可以是对引人特性的版本描述。例如， ©since version 1.7.10

• @deprecated 文本
  这个标记将对类、 方法或变量添加一个不再使用的注释。文本中给出了取代的建议。
  例如， @deprecated Use <code> setVIsible(true)</code> instead
  通过 @see 和@link标记，可以使用超级链接， 链接到 javadoc 文档的相关部分或外
  部文档。
  ®see 引用
  这个标记将在“ see also” 部分增加一个超级链接。它可以用于类中，也可以用于方法中。这里的引用可以选择下列情形之一：

package,class#feature label
<a href="...">label</a>
"text"

第一种情况是最常见的。只要提供类、 方法或变量的名字，javadoc 就在文档中插入一个超链接。例如，

@see com.horstraann.corejava.Employee#raiseSalary(double)

        建立一个链接到 com.horstmann.corejava.Employee 类的 raiseSalary(double) 方法的超链接。 可以省略包名，甚至把包名和类名都省去，此时，链接将定位于当前包或当前类。
        需要注意，一定要使用井号（#)， 而不要使用句号（.）分隔类名与方法名，或类名与变量名。Java 编译器本身可以熟练地断定句点在分隔包、 子包、 类、内部类与方法和变量时的不同含义。但是 javadoc 实用程序就没有这么聪明了，因此必须对它提供帮助。
        如果 @see 标记后面有一个 < 字符，就需要指定一个超链接。可以超链接到任何URL。例如：

@see <a href="www.horstmann.com/corejava. html ">The Core ]ava home page</a>

        在上述各种情况下， 都可以指定一个可选的标签（ label ) 作为链接锚（link anchor) 。如果省略了 label , 用户看到的锚的名称就是目标代码名或 URL。
        如果@see 标记后面有一个双引号（"）字符，文本就会显示在 “see also” 部分。例如，
@see "Core Java 2 volume 2n
        可以为一个特性添加多个 @see 标记，但必须将它们放在一起.

• @link
  可以在注释中的任何位置放置指向其他类或方法的超级链接， 以及
  插人一个专用的标记， 例如， {@link package,classifeature label ]
  这里的特性描述规则与@see 标记规则一样