3.1 Java注释
在编写程序时，为了说明某段代码的用途、某个方法的功能、某个方法的参数或者输入/输出值等的含义，需要在程序的关键部分加一些注释。各种编程语言都提供了各自的用于放置到程序代码中的注释语句，这些语句和程序语句混杂在一块，因此，需要一种特殊的机制让注释和代码不会在编译时发生冲突和混淆。比如，在VB中可用单引号“'”表示单行注释等。和其他语言相比较，Java语言提供的注释方式更灵活，更多样，更强大。
Java语言提供了3种注释方式，分别为短（单行）注释、块（多行）注释及文档注释。单行和多行注释很容易理解，编译和运行时会将这部分内容忽略。
Java语言中比较特殊的是javadoc注释，包含在这部分中的注释可以通过javadoc命令自动生成API文档。使用javadoc工具，可以保证程序代码和技术文档的同步。在修改程序中的注释后，只需要使用javadoc工具，就可以方便地生成相应的技术文档。
3.1.1 知识准备：Java注释使用规则
（1）单行注释：单行注释就是在程序中注释一行代码。
注释规则：在代码中单起一行注释，注释前最好有一行空行，并与其后的代码具有一样的缩进层级。如果单行无法完成，则应采用多行注释。
注释格式如下。
//注释内容
（2）多行注释：一次对程序中的多行代码进行注释。
注释规则：注释若干行，通常用于说明文件、方法、数据结构等的意义与用途，或者描述算法，一般位于一个文件或者一个方法的前面，起引导的作用，也可以根据需要放在合适的位置。
注释格式如下。
/ *
注释内容
* /
单行注释和多行注释的应用示例如下。
源文件：Message Comment.java。具体示例代码如下。
//这是一个单行注释
/ *
这是一个
多行注释
* /
publicclass Message Comment{
publicstaticvoidmain(String[]args){
System.out.println("发信息");
//System.out.println("此条信息不会显示");
}
}
3.1.2 知识准备：利用javadoc生成API文档
在软件开发过程中，文档的重要性不亚于程序代码本身。如果代码与文档是分离的，那么在每次修改代码时都需要修改相应的文档，这会是一件很麻烦的事情。Java中有一种特别的注释方式，即文档注释。利用这种注释，可以通过javadoc将代码同文档“连接”起来，从Java源文件中提取这些注释的内容，可以生成HTML格式的API文档。
文档注释的基本格式如下。
/ **
文档注释内容
* /
这里需要注意文档注释和多行注释的区别，文档注释的开始标记是“/ **”，而多行注释的开始标记是“/ *”。
由于文档注释最重要的功能就是生成HTML格式的API文档，因此很多用于HTML格式化的HTML标记也可以用在文档注释中。从这些注释中提取注释并生成HTML文件的时候，在生成的HTML文件中将使用这些HTML标记来格式化HTML文件内容。常用的HTML标记有<b>…</b>、<code>…</code>等，关于这些HTML标记及其他HTML标记的含义，请读者参考相关的HTML资料。
文档注释和多行注释的另一个不同之处是，文档注释并不可以放在Java代码的任何地方，因为利用javadoc工具从Java代码中提取注释并生成API文档时，主要从包、公有（public）类与接口、公有方法和受保护（protected）方法、公有属性和受保护属性几项内容中提取信息，因此，文档注释也应该放到相应的位置。
1．文档注释位置
（1）类注释。类注释用于说明整个类的功能、特性等，它应该放在所有import语句之后，在class定义之前。
这个规则也适用于接口（interface）注释。
（2）方法注释。方法注释用来说明方法的定义，比如方法的参数、返回值及作用等。方法注释应该放在它所描述的方法定义前面。
（3）属性注释。默认情况下，javadoc只对公有（public）属性和受保护（protected）属性产生文档，通常是静态常量。
（4）包注释。类、方法、属性的注释直接放到Java源文件中，而对于包的注释，无法放到Java文件中去，只能通过在包对应的目录中添加一个package.html文件来达到这个目的。当生成HTML文件时，package.html文件的<body>…</body>部分的内容将会被提取出来作为包的说明。关于包注释，本书后面还会有更进一步的解释。
（5）概要注释。除了包注释外，还有一种类型的文档无法从Java源文件中提取，就是对所有类文件提供概要说明的文件。同样，为这类注释单独新建一个 HTML 文件，这个文件的名字为overview.html，它的<body>和</body>标记之间的内容也可以都被提取。
2．javadoc标记
在文档注释中，常用@来表示一个javadoc标记，常用的javadoc标记如下所述。
● @author：作者。
● @version：版本。
● @docroot：产生文档的根路径。
● @deprecated：不推荐使用的方法。
● @param：方法的参数类型。
● @return：方法的返回类型。
● @see：指定参考的内容。
● @exception：抛出的异常。
● @throws：抛出的异常，和@exception同义。
需要注意的是，这些标记的使用是有位置限制的，其中可以出现在类或者接口文档注释中的标记有@see、@deprecated、@author、@version等；可以出现在方法或者构造器文档注释中的标记有@see、@deprecated、@param、@return、@throws及@exception等；可以出现在属性文档注释中的标记有@see、@deprecated等。
3．javadoc命令语法
javadoc的命令语法如下，参数可以按照任意顺序排列。
javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]
（1）packagenames：包列表这个选项可以是一系列的包名（用空格隔开），例如，java.lang java.lang.reflect java.awt。因为javadoc不递归作用于子包，不允许对包名使用通配符，所以必须显式地列出希望建立API文档的每一个包。
（2）sourcefiles：源文件列表。这个选项可以是一系列源文件名（用空格隔开），可以使用通配符。javadoc允许4种源文件：类源代码文件、包描述文件、总体概述文件、其他杂文件。
● 类源代码文件：类或者接口的源代码文件。
● 包描述文件：每一个包都可以有自己的包描述文件。包描述文件的名称必须是package.html，与包的.java文件放置在一起。包描述文件的内容通常是使用HTML标记写的。javadoc执行时将自动寻找包描述文件，如果找到，javadoc将首先对描述文件中<body>…</body>之间的内容进行处理，然后把处理结果放到该包的Package Summary页面中，最后把包描述文件的第一句（紧靠<body>）放到输出的Overview Summary页面中，并在语句前面加上该包的包名。
● 总体概述文件：javadoc可以创建一个总体概述文件来描述整个应用或者所有包。总体概述文件可以被任意命名，也可以放置到任意位置。-overview选项可以指示总体概述文件的路径和名称。总体概述文件的内容是使用HTML标记写的，javadoc在执行的时候，如果发现-overview选项，会首先对文件中<body>…</body>之间的内容进行处理；然后把处理后的结果放到输出的Overview Summary 页面的底部；最后把总体概述文件中的第一句放到输出的Overview Summary页面的顶部。
● 其他杂文件：这些文件通常是指与javadoc输出的HTML文件相关的一些图片文件、Java源代码文件（.java）、Java程序（.class）、Java小程序（Applets）及HTML文件。这些文件必须放在doc-files目录中。每一个包都可以有自己的doc-files目录。例如要在java.awt.Button的 HTML 文档中使用一幅按钮的图片（Button.gif），首先必须把图片文件放到java\awt\doc-files\中，然后在Button.java文件中加入以下注释。
/ **
* This button looks like this:
*<img src="doc-files/Button.gif">
* /
（3）@files：包含的文件。为了简化javadoc命令，可以把需要建立API文档的文件名和包名放在一个或多个文本文件中。例如简化以下命令。
javadoc -d apidoc com.oristand.college com.oristand.school
可以建立一个名称为mypackage.txt的文件，其内容如下。
com.oristand.college
com.oristand.school
然后执行以下命令。
javadoc -d apidoc @mypackage.txt
（4）options：命令行选项。
① public：只显示公共类及成员。
② protected：只显示受保护的和公共的类及成员，是默认选项。
③ package：只显示包、受保护的和公共的类及成员。
④ private：显示所有类和成员。
-classpath classpathlist 指定javadoc查找“引用类”的路径。引用类是指带文档的类加上它们引用的任何类。javadoc将搜索指定路径下的所有子目录，classpathlist可以包含多个路径（使用“;”隔开）。
一切就绪后，就可以使用JDK中的javadoc工具生成相关的API文档。
3.1.3 任务一：使用javadoc生成API文档
1．任务描述
写一段代码，加入文档注释，并使用javadoc工具生成相关API文档。
2．技能要点
● 添加文档注释。
● 使用javadoc命令生成API文档。
3．任务实现过程
（1）编写一个Java Doc类，声明变量，并加入文档注释。
源文件：Java Doc.java。具体示例代码如下。
/ **
* javadoc演示程序--<b>Java Doc</b>
*
*@author Alex Wen
*@version 1.0 2009/12/15
* /
public class Java Doc {
/ **
* 在main()方法中使用的显示用的字符串
*
*@see #main(java.lang.String[])
* /
static String SDisplay;
static String 变量;
/ **
* 显示Java Doc
*
*@param args
* 从命令行中输入字符串
* /
public static void main(String args[]) {
SDisplay ="Hello World ";
变量 ="test";
System.out.println(SDisplay+ 变量);
}
}
（2）用如下javadoc命令生成API文档，在控制台上将会列出正在生成的文件。
javadoc -private -d doc -author -version Java Doc.java
从图3-1中可以看出生成了哪些文件。
（3）打开index.html文件，如图3-2所示，因为没有包，所以没有包列表文件。
图3-1 生成的API文档
图3-2 生成的index.html显示结果