一、注释
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 标记规则一样