关于Java的注释

副标题#e#

对付Java注释我们主要相识两种：

// 注释一行

/* …… */ 注释若干行

但尚有第三种，文档注释：

/** …… */ 注释若干行，并写入 javadoc 文档

凡是这种注释的多行写法如下：

/**

* ………

* ………

*/

许多人多忽视了这第三种注释，那么这第三种注释有什么用？javadoc 又是什么对象？下面我们就谈谈。

一. Java 文档和 Javadoc

Java 措施员都应该知道利用 JDK 开拓，最好的辅佐信息就来自 SUN 宣布的 Java 文档。它分包、分类具体的提供了各要领、属性的辅佐信息，具有具体的类树信息、索引信息等，并提供了很多相关类之间的干系，如担任、实现接口、引用等。

Java 文档全是由一些 html 文件组织起来的，在 SUM 的站点上可以下载它们的压缩包。可是你必定想不到，这些文档我们可以本身生成。——就此打住，再吊一次胃口。

安装了 JDK 之后，安装目次下有一个 src.jar 文件可能 src.zip 文件，它们都是以 ZIP 名目压缩的，可以利用 WinZip 解压。解压之后，我们就可以看到分目次放的全是 .java 文件。是了，这些就是 Java 运行类的源码了，很是完整，连注释都写得一清二楚……不外，怎么看这些注释都有点似曾领会的感受？

这就不奇怪了，我们的迷底也将近揭开了。假如你仔细比拟一下 .java 源文件中的文档注释 (/** … */) 和 Java 文档的内容，你会发明它们就是一样的。Java 文档只是还在名目和排版上下了些工夫。再仔细一点，你会发明 .java 源文件中的注释还带有 HTML 标识，如 ＜B＞、＜BR＞、＜Code＞ 等，在 Java 文档中，该呈现这些标识的处所，已经按标识的的界说举办了排版。

终于真像懂得了，本来 Java 文档是来自这些注释。难怪这些注释叫做文档注释呢！不外，是什么东西把这些注释酿成文档的呢？

是该请出 javadoc 的时候了。在 JDK 的 bin 目次下你可以找到 javadoc，假如是 Windows 下的 JDK，它的文件名为 javadoc.exe。利用 javdoc 编译 .java 源文件时，它会读出 .java 源文件中的文档注释，并凭据必然的法则与 Java 源措施一起举办编译，生成文档。

先容 javadoc 的编译呼吁之前，照旧先相识一下文档注释的名目吧。不外为了可以或许编译下面提到的若干例子，这里先先容一条 javadoc 呼吁：

javadoc -d 文档存放目次 -author -version 源文件名.java

这条呼吁编译一个名为 “源文件名.java”的 java 源文件，并将生成的文档存放在“文档存放目次”指定的目次下，生成的文档中 index.html 就是文档的首页。-author 和 -version 两上选项可以省略。

#p#副标题#e#

二. 文档注释的名目

文档注释可以用于对类、属性、要领等举办说明。写文档注释时除了需要利用 /** …. */ 限定之外，还需要留意注释内部的一些细节问题。

1. 文档和文档注释的名目化

生成的文档是 HTML 名目，而这些 HTML 名目标标识符并不是 javadoc 加的，而是我们在写注释的时候写上去的。好比，需要换行时，不是敲入一个回车符，而是写入 ＜br＞，假如要分段，就应该在段前写入 ＜p＞。

因此，名目化文档，就是在文档注释中添加相应的 HTML 标识。

文档注释的正文并不是直接复制到输出文件 (文档的 HTML 文件)，而是读取每一行后，删掉前导的 * 号及 * 号以前的空格，再输入到文档的。如

/**
* This is first line. ＜br＞
***** This is second line. ＜br＞
This is third line.
*/

编译输出后的 HTML 源码则是

This is first line. ＜br＞
This is second line. ＜br＞
This is third line.

前导的 * 号答允持续利用多个，其结果和利用一个 * 号一样，但多个 * 号前不能有其它字符脱离，不然脱离符及后头的 * 号都将作为文档的内容。* 号在这里是作为左界线利用，如上例的第一行和第二行；假如没有前导的 * 号，则界线从第一个有效字符开始，而不包罗前面的空格，如上例第三行。

尚有一点需要说明，文档注释只说明紧接其后的类、属性可能要领。如下例：

/** comment for class */
public class Test {
/** comment for a attribute */
int number;
/** comment for a method */
public void myMethod() { ...... }
......
}

上例中的三处注释就是别离对类、属性和要领的文档注释。它们生成的文档别离是说明紧接其后的类、属性、要领的。“紧接”二字尤其重要，假如忽略了这一点，就很大概造成生成的文档错误。如

import java.lang.*;
/** commnet for class */
public class Test { ...... }
// 此例为正确的例子

这个文档注释将生成正确的文档。但只需要改变个中两行的位置，酿成下例，就会堕落：

/** commnet for class */
import java.lang.*;
public class Test { ...... }
// 此例为错误的例子

这个例子只把上例的 import 语句和文档注释部门互换了位置，功效却大不沟通——生成的文档中基础就找不到上述注释的内容了。原因安在？

#p#分页标题#e#

“/** commnet for class */”是对 class Test 的说明，把它放在“public class Test { …… }”之前时，其后紧接着 class Test，切正当则，所以生成的文档正确。可是把它和“import java.lang.*;”变更了位置后，其后紧接的就是不 class Test 了，而是一个 import 语句。由于文档注释只能说明类、属性和要领，import 语句不在此列，所以这个文档注释就被看成错误说明省略掉了。

2. 文档注释的三部门

按照在文档中显示的结果，文档注释分为三部门。先举譬喻下，以便说明。

/**
* show 要领的简述.
* ＜p＞show 要领的具体说明第一行＜br＞
* show 要领的具体说明第二行
* @param b true 暗示显示，false 暗示埋没
* @return 没有返回值
*/
public void show(boolean b) {
frame.show(b);
}

第一部门是简述。文档中，对付属性和要领都是先有一个列表，然后才在后头一个一个的具体的说明。列表中属性名可能要领名后头那段说明就是简述。如下图中被红框框选的部门：

#p#副标题#e#

简述部门写在一段文档注释的最前面，第一个点号 (.) 之前 (包罗点号)。换句话说，就是用第一个点号脱离文档注释，之前是简述，之后是第二部门和第三部门。如上例中的 “* show 要领的简述.”。

有时，纵然正确地以一个点号作为脱离，javadoc 仍然会堕落，把点号后头的部门也做为了第一部门。为了办理这个问题，我们可以利用一个 ＜p＞ 符号将第二分部门开为下一段，如上例的“* ＜p＞show 要领的具体说明第一行 ….”。除此之外，我们也可以利用 ＜br＞ 来脱离。

第二部门是具体说明部门。该部门对属性可能要领举办具体的说明，在名目上没有什么非凡的要求，可以包括若干个点号。它在文档中的位置如下图所示：

这部门文档在上例中相应的代码是：

　　* show 要领的简述.
　　* ＜p＞show 要领的具体说明第一行＜br＞
　　* show 要领的具体说明第二行

发明什么了？对了，简述也在个中。这一点要记着了，不要多此一举——在具体说明部门中再写一次简述哦！

第三部门是非凡说明部门。这部门包罗版本说明、参数说明、返回值说明等。它在文档中的位置：

第三部门在上例中相应的代码是

　　* @param b true 暗示显示，false 暗示埋没
　　* @return 没有返回值

除了 @param 和 @return 之外，尚有其它的一些非凡标志，别离用于对类、属性和要领的说明……不要推我，我顿时就说。

三. 利用 javadoc 标志

javadoc 标志是插入文档注释中的非凡标志，它们用于标识代码中的非凡引用。javadoc 标志由“@”及其后所跟的标志范例和专用注释引用构成。记着了，三个部门——@、标志范例、专用注释引用。不外我甘愿把它分成两部门：@ 和标志范例、专用注释引用。固然 @ 和 标志范例之间有时可以用空格符脱离，可是我甘愿始终将它们紧挨着写，以淘汰堕落时机。

javadoc 标志有如下一些：

标志	用于	浸染
@author	对类的说明	标明开拓该类模块的作者
@version	对类的说明	标明该类模块的版本
@see	对类、属性、要领的说明	参考转向，也就是相关主题
@param	对要领的说明	对要领中某参数的说明
@return	对要领的说明	对要领返回值的说明
@exception	对要领的说明	对要领大概抛出的异常举办说明

#p#副标题#e#

下面具体说明各标志。

1. @see 的利用

@see 的句法有三种：

　　@see 类名
　　@see #要领名或属性名
　　@see 类名#要领名或属性名

类名，可以按照需要只写出类名 (如 String) 可能写出类全名 (如 java.lang.String)。那么什么时候只需要写出类名，什么时候需要写出类全名呢？

#p#分页标题#e#

假如 java 源文件中的 import 语句包括了的类，可以只写出类名，假如没有包括，则需要写出类全名。java.lang 也已经默认被包括了。这和 javac 编译 java 源文件时的划定一样，所以可以简朴的用 javac 编译来判定，源措施中 javac 能找到的类，javadoc 也必然能找到；javac 找不到的类，javadoc 也找不到，这就需要利用类全名了。

要领名可能属性名，假如是属性名，则只需要写出属性名即可；假如是要领名，则需要写出要领名以及参数范例，没有参数的要领，需要写出一对括号。如

成员范例	成员名称及参数	@see 句法
属性	number	@see number
属性	count	@see count
要领	count()	@see count()
要领	show(boolean b)	@see show(boolean)
要领	main(String[] args)	@see main(String[])

有时也可以偷懒：如果上例中，没有 count 这一属性，那么参考要领 count() 就可以简写成 @see count。不外，为了安详起见，照旧写全 @see count() 较量好。

@see 的第二个句法和第三个句法都是转向要领可能属性的参考，它们有什么区别呢？

第二个句法中没有指出类名，则默认为当前类。所以它界说的参考，都转向本类中的属性可能要领。而第三个句法中指出了类名，则还可以转向其它类的属性可能要领。

关于 @see 标志，我们举个例说明。由于 @see 在对类说明、对属性说明、对要领说明时用法都一样，所以这里只以对类说明为例。

/**
* @see String
* @see java.lang.StringBuffer
* @see #str
* @see #str()
* @see #main(String[])
* @see Object#toString()
*/
public class TestJavaDoc {
}

生成的文档的相关部门如下图：

String 和 StringBuffer 都是在 java.lang 包中，由于这个包是默认导入了的，所以这两个类可以直接写类名，也可以写类全名。str、str() 为同名属性和要领，所以要领名需要用 () 区分。main 是带参数的要领，所以在 () 中指明白参数范例。toString() 固然在本类中也有 (从 Object 担任的)，但我们是想参考 Object 类的 toString() 要领，所以利用了 Object#toString()。

奇怪的是，为什么个中只有 str、str() 和 main(String[]) 酿成了链接呢？那是因为编译时没有把 java.lang 包可能 Stirng、StringBuffer、Object 三个类的源文件一起插手编译，所以，生成的文档没有关于那三个类的信息，也就不行以成立链接了。后头讲授 javadoc 编译呼吁的时候还会具体说明。

上例中假如去把类中的 str 属性去掉，那么生成的文档又会有什么变革呢？你会发明，本来是 str, str()，而此刻酿成了 str(), str()，因为 str 属性已经没有了，所以 str 也暗示要领 str()。

#p#副标题#e#

2. 利用 @author、@version 说明类

这两个标志别离用于指明类的作者和版本。缺省环境下 javadoc 将其忽略，但呼吁行开关 -author 和 -version 可以修改这个成果，使其包括的信息被输出。这两个标志的句法如下：

@author 作者名

@version 版本号

个中，@author 可以多次利用，以指明多个作者，生成的文档中每个作者之间利用逗号 (,) 离隔。@version 也可以利用多次，只有第一次有效，生成的文档中只会显示第一次利用 @version 指明的版本号。如下例

/**
* @author Fancy
* @author Bird
* @version Version 1.00
* @version Version 2.00
*/
public class TestJavaDoc {
}

生成文档的相关部门如图：

#p#分页标题#e#

从生成文档的图示中可以看出，两个 @author 语句都被编译，在文档中生成了作者列表。而两个 @version 语句中只有第一句被编译了，只生成了一个版本号。—www.bianceng.cn

从图上看，作者列表是以逗号脱离的，假如我想分行显示怎么办？别的，假如我想显示两个以上的版本号又该怎么办？

——我们可以将上述两条 @author 语句合为一句，把两个 @version 语句也合为一句：

@author Fancy＜br＞Bird

@version Version 1.00＜br＞Version 2.00

功效如图：

我们这样做即到达了目标，又没有粉碎法则。@author 之后的作者名和 @version 之后的版本号都可以是用户本身界说的任何 HTML 名目，所以我们可以利用 ＜br＞ 标志将其分行显示。同时，在一个 @version 中指明两个用 ＜br＞ 脱离的版本号，也没有粉碎只显示第一个 @version 内容的法则。

#p#副标题#e#

3. 利用 @param、@return 和 @exception 说明要领

这三个标志都是只用于要领的。@param 描写要领的参数，@return 描写要领的返回值，@exception 描写要领大概抛出的异常。它们的句法如下：

@param 参数名 参数说明

@return 返回值说明

@exception 异常类名 说明

每一个 @param 只能描写要领的一个参数，所以，假如要领需要多个参数，就需要多次利用 @param 来描写。

一个要领中只能用一个 @return，假如文档说明中列了多个 @return，则 javadoc 编译时会发出告诫，且只有第一个 @return 在生成的文档中有效。

要领大概抛出的异常该当用 @exception 描写。由于一个要领大概抛出多个异常，所以可以有多个 @exception。每个 @exception 后头应有简述的异常类名，说明中应指出抛出异常的原因。需要留意的是，异常类名应该按照源文件的 import 语句确定是写出类名照旧类全名。 　　示譬喻下：

public class TestJavaDoc {
/**
* @param n a switch
* @param b excrescent parameter
* @return true or false
* @return excrescent return
* @exception java.lang.Exception throw when switch is 1
* @exception NullPointerException throw when parameter n is null
*/
public boolean fun(Integer n) throws Exception {
switch (n.intValue()) {
case 0:
break;
case 1:
throw new Exception("Test Only");
default:
return false;
}
return true;
}
}

利用 javadoc 编译生成的文档相关部门如下图：

可以看到，上例中 @param b excrescent parameter 一句是多余的，因为参数只是一个 n，并没有一个 b５是 javadoc 编译时并没有查抄。因此，写文档注释时必然要正确匹配参数表与要领中正式参数表的项目。假如要领参数表中的参数是 a，文档中却给出对参数 x 的表明，可能再多出一个参数 i，就会让人摸不着脑子了。@exceptin 也是一样。

上例措施中并没有抛出一个 NullPointerException，可是文档注释中为什么要写上这么一句呢，莫非又是为了演示？这不是为了演示描写多余的异常也能通过编译，而是为了说明写异常说明时应考运行时 (RunTime) 异常的大概性。上例措施中，假如参数 n 是给的一个空值 (null)，那么措施会在运行的时候抛出一个 NullPointerException，因此，在文档注释中添加了对 NullPointerException 的说明。

上例中的 @return 语句有两个，可是按照法则，同一个要领中，只有第一个 @return 有效，其余的会被 javadoc 忽略。所以生成的文档中没有呈现第二个 @return 的描写。

讲到这里，该怎么写文档注释你应该已经清楚了，下面就开始讲授 javadoc 的常用呼吁。

#p#副标题#e#

四. javadoc 呼吁

运行 javadoc -help 可以看到 javadoc 的用法，这里罗列常用参数如下：

用法：

javadoc [options] [packagenames] [sourcefiles]

选项：

-public 仅显示 public 类和成员

-protected 显示 protected/public 类和成员 (缺省)

-package 显示 package/protected/public 类和成员

-private 显示所有类和成员

-d ＜directory＞ 输出文件的方针目次

-version 包括 @version 段

-author 包括 @author 段

-splitindex 将索引分为每个字母对应一个文件

-windowtitle ＜text＞ 文档的欣赏器窗口标题

javadoc 编译文档时可以给定包列表，也可以给出源措施文件列表。譬喻在 CLASSPATH 下有两个包若干类如下：

fancy.Editor

fancy.Test

fancy.editor.ECommand

fancy.editor.EDocument

fancy.editor.EView

这里有两个包 (fancy 和 fancy.editor) 和 5 个类。那么编译时 (Windows 情况) 可以利用如下 javadoc 呼吁：

javadoc fancyTest.java fancyEditor.java fancyeditorECommand.java fancyeditorEDocument.java fancyeditorEView.java

这是给出 java 源文件作为编译参数的要领，留意呼吁中指出的是文件路径，应该按照实际环境改变。也可以是给出包名作为编译参数，如：

javadoc fancy fancy.editor

用欣赏器打开生成文档的 index.html 文件即可发明两种方法编译功效的差异，如下图：

#p#副标题#e#

#p#分页标题#e#

用第二条呼吁生成的文档被框架分成了三部门：包列表、类列表和类说明。在包列表中选择了某个包之后，类列表中就会列出该包中的所有类；在类列表中选择了某个类之后，类说明部门就会显示出该类的具体文档。而用第一条呼吁生成的文档只有两部门，类列表和类说明，没有包列表。这就是两种方法生成文档的最大区别了。

两种方法编译尚有一点差异，

下面再来细说选项。

-public、-protected、-package、-private 四个选项，只需要任选其一即可。它们指定的显示类成员的水平。它们显示的成员几多是一个包括的干系，如下表：

-private (显示所有类和成员)

-package (显示 package/protected/public 类和成员)

-protected (显示 protected/public 类和成员)

-public (仅显示 public 类和成员)

-d 选项答允你界说输出目次。假如不消 -d 界说输出目次，生成的文档文件会放在当前目次下。-d 选项的用法是

-d 目次名

目次名为必填项，也就是说，假如你利用了 -d 参数，就必然要为它指定一个目次。这个目次必需已经存在了，假如还不存在，请在运行 javadoc 之前建设该目次。

-version 和 -author 用于节制生成文档时是否生成 @version 和 @author 指定的内容。不加这两个参数的环境下，生成的文档中不包括版本和作者信息。

-splitindex 选项将索引分为每个字母对应一个文件。默认环境下，索引文件只有一个，且该文件中包括所有索引内容。虽然生成文档内容不多的时候，这样做很是符合，可是，假如文档内容很是多的时候，这个索引文件将包括很是多的内容，显得过于复杂。利用 -splitindex 会把索引文件按各索引项的第一个字母举办分类，每个字母对应一个文件。这样，就减轻了一个索引文件的承担。

-windowtitle 选项为文档指定一个标题，该标题会显示在窗口的标题栏上。假如不指定该标题，而默认的文档标题为“生成的文档（无标题）”。该选项的用法是：

-windowtitle 标题

标题是一串没有包括空格的文本，因为空格符是用于脱离各参数的，所以不能包括空格。同 -d 雷同，假如指定了 -windowtitle 选项，则必需指定标题文本。

到此为止，Java 文档和 javadoc 就先容完了。