Java 基础教程

Java 面向对象

Java 高级教程

Java 笔记

Java 注释


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

注释的插入

javadoc 实用程序(utility)从下面几个特性中抽取信息:

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

应该为上面几部分编写注释、注释应该放置在所描述特性的前面。注释以 /** 开始,并以 */ 结束。

每个 /** . . . */ 文档注释在标记之后紧跟着自由格式文本(free-form text)。标记由 @ 开始,如 @author 或 @param。

自由格式文本的第一句应该是一个概要性的句子。javadoc 实用程序自动地将这些句子抽取出来形成概要页。

在自由格式文本中,可以使用 HTML 修饰符,例如,用于强调的 <em>...</em>、用于着重强调的 <strong>...</strong> 以及包含图像的 <img ...> 等。不过,一定不要使用 <h1> 或 <hr>,因为它们会与文档的格式产生冲突。若要键入等宽代码,需使用{@code...}而不是 <code>...</code>,这样一来,就不用操心对代码中的 < 字符转义了。

类注释

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

package demo;

import static java.lang.System.out;

/**
 * demo
 */
public class KnowledgeDict {

    public static void main(String[] args) {
        out.println("Hello World");
    }
}

没有必要在每一行的开始用星号 *,例如,以下注释同样是合法的:

/**
   demo
 */
public class KnowledgeDict {

    public static void main(String[] args) {
        out.println("Hello World");
    }
}

方法的注释

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

  • @param 变量描述

    这个标记将对当前方法的“param”(参数)部分添加一个条目。这个描述可以占据多行,并可以使用 HTML 标记。一个方法的所有 @param 标记必须放在一起。

  • @return 描述

    这个标记将对当前方法添加“return”(返回)部分。这个描述可以跨越多行,并可以使用 HTML 标记。

  • @throws 类描述

    这个标记将添加一个注释,用于表示这个方法有可能抛出异常。

/**
 * parseLong
 *
 * @param input
 * @return
 * @throws NumberFormatException
 */
public long parseLong(String input) throws NumberFormatException {
    long l = Long.parseLong(input);
    return l;
}

域注释

只需要对公有域(通常指的是静态常量)建立文档。

/**
 * annotation
 */
public static final int ANNOTATION = 1;

通用注释

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

  • @author 姓名

    这个标记将产生一个“author”(作者)条目。可以使用多个 @author 标记,每个 @author 标记对应一个作者。

  • @version 文本

    这个标记将产生一个“version”(版本)条目。这里的文本可以是对当前版本的任何描述。下面的标记可以用于所有的文档注释中。

  • @since 文本

    这个标记将产生一个“since”(始于)条目。这里的 text 可以是对引人特性的版本描述。

  • @deprecated 文本

    这个标记将对类、方法或变量添加一个不再使用的注释。文本中给出了取代的建议。

  • @see 引用

    这个标记将在“see also”部分增加一个超级链接。它可以用于类中,也可以用于方法中。