java学习（五） 文档注释

注释的插入

javadoc工具可以由源文件生成一个HTML文件。javadoc实用程序从下面几个特性中抽取信息：
1.包
2.公有类与接口
3.公有的和受保护的构造器及方法
4.公有的和受保护的域
应该为上面几部分编写注释。注释应该放置在所描述特性的前面，以/**开始，并以*/结束。每个文档注释在标记之后紧跟着自由文本格式（free-form text）。标记由@开始，如@author或@param。
自由格式文本的第一句应该是一个概要性的句子。javadoc应用程序自动地将这些句子抽取出来形成概要页。

通用注释

下面的标记可以用在类文档的注释中。

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

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

• @since文本
  产生一个“since”（始于）条目。这里的文本可以是对引入特性的版本描述。
• @see文本
  这个标记将在“see also”部分增加一个超级链接。

类注释

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

方法注释

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

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