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类描述
    这个标记将添加一个注释,用于表示这个方法有可能抛出异常。

推荐阅读更多精彩内容