2.6 注释

与其他编程语言一样，Java的源代码中也允许出现注释，并且注释也不会影响程序的执行，只是起到提示开发人员的作用。因此，注释的内容可以有很多，而不必担心影响执行速度。在Java中，有三种不同功能的注释，分别为单行注释、区域注释与文档注释，本节将对这些注释的使用进行介绍。

2.6.1 单行注释

这种注释方式是最常用的，用来表示单行的注释信息。其语法为用“//”表示注释开始，注释内容从“//”开始到本行结尾，例如：

    System.out.println("Welcome to Java!!!");  //打印Welcome to Java!!!

2.6.2 区域注释

如果需要较长的多行注释时，可使用区域注释。此种注释以“/*”开始，之后是注释内容，且可跨越多行，最后以“*/”结束。例如：

    /* 这是本书的第一个例子
    作者：zhangsan
    */

而许多开发人员在区域注释内容的每行都习惯以“*”开头，例如：

    /*这是本书的第一个例子
    *作者：zhangsan
    */

但编译时，在“/*”及“*/”之间的内容都会被忽略，所以上述两种风格的注释没什么异样，只是一种使用习惯而已，读者可以根据自己的喜好决定具体使用哪一种。

2.6.3 文档注释

JDK提供了为自己的代码自动生成API网页的工具，本小节将介绍如何使用该工具。请读者按如下步骤操作。

（1）新建一个名称为SampleDoc.java的源文件，在其中输入如下代码。

    1   /**
    2   *一个例子(文档注释)
    3   */
    4   public class SampleDoc
    5   {
    6          /**
    7          *主方法(文档注释)
    8          */
    9          //普通单行注释
    10         /*
    11         *普通多行注释
    12         */
    13       public static void main(String args[])
    14       {
    15         System.out.println("文档注释的例子。");
    16       }
    17  }

· 由“/**”开头、“*/”结尾的为文档注释。

· 文档注释的内容未来经过工具的处理会出现在生成的API网页中。

· 普通注释的内容不会出现在生成的API网页中。

（2）打开命令提示符窗口，将当前路径设置到SampleDoc.java文件所在的目录，用如下命令处理源文件。

    javadoc SampleDoc.java

（3）此时命令提示符窗口中会显示处理的过程，如图2-23所示。

图2-23 生成API网页的过程

（4）在处理完成后，在源代码所在的文件夹中会出现很多HTML文件，这就是系统自动生成的API网页，如图2-24所示。

图2-24 生成的HTML文件

（5）用浏览器打开index.html文件，可以看到文档注释中的内容出现在网页中的对应位置，如图2-25所示。

图2-25 index.html文件

从上述过程可以看出，使用JDK提供的javadoc工具自动生成API帮助文档是非常方便的。