除嵌入 HTML 和@see 引用之外,方法还允许使用针对参数、返回值以及违例的文档标记。
1、 @param 格式如下: @param 参数名 说明
其中,“参数名”是指参数列表内的标识符,而“说明”代表一些可延续到后续行内的说明文字。一旦遇到 一个新文档标记,就认为前一个说明结束。可使用任意数量的说明,每个参数一个。
2、 @return 格式如下: @return 说明
其中,“说明”是指返回值的含义。它可延续到后面的行内。
3、 @exception 违例
简言之,它们是一些特殊的对象,若某个方 法失败,就可将它们“扔出”对象。调用一个方法时,尽管只有一个违例对象出现,但一些特殊的方法也许 能产生任意数量的、不同类型的违例。所有这些违例都需要说明。所以,违例标记的格式如下: @exception 完整类名 说明 其中,“完整类名”明确指定了一个违例类的名字,它是在其他某个地方定义好的。而“说明”(同样可以 延续到下面的行)告诉我们为什么这种特殊类型的违例会在方法调用中出现。
4、 @deprecated 该标记用于指出一些旧功能已由改进过的新功能取代
该标记的作用是建议用户不 必再使用一种特定的功能,因为未来改版时可能摒弃这一功能。若将一个方法标记为@deprecated,则使用该 方法时会收到编译器的警告。
具体的使用请参见下方的代码:
import java.util.*;
/** The first Thinking in Java example program.
* Lists system information on current machine.
* @author Bruce Eckel
* @author http://www.BruceEckel.com
* @version 1.0
*/
public class Property {
/** Sole entry point to class & application
* @param args array of string arguments
* @return No return value
* @exception exceptions No exceptions thrown
*/
public static void main(String[] args) {
System.out.println(new Date());
Properties p = System.getProperties();
p.list(System.out);
System.out.println("--- Memory Usage:");
Runtime rt = Runtime.getRuntime();
System.out.println("Total Memory = "
+ rt.totalMemory()
+ " Free Memory = "
+ rt.freeMemory());
}
}