javadoc 使用

对于 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 两上选项可以省略。
　　二. 文档注释的格式
　　文档注释可以用于对类、属性、方法等进行说明。写文档注释时除了需要使用 /** .... */ 限定之外，还需要注意注释内部的一些细节问题。
　　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 语句和文档注释部分 交换 了位置，结果却大不相同——生成的文档中根本就找不到上述注释的内容了。原因何在？
　　“/** 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);
　　} 
　　第一部分是简述。文档中，对于属性和方法都是先有一个列表，然后才在后面一个一个的详细的说明。列表中属性名或者方法名后面那段说明就是简述。如下图中被红框框选的部分：
　　　  
　　简述部分写在一段文档注释的最前面，第一个点号 (.) 之前 (包括点号)。换句话说，就是用第一个点号分隔文档注释，之前是简述，之后是第二部分和第三部分。如上例中的 “* show 方法的简述.”。
　　有时，即使正确地以一个点号作为分隔， javadoc  仍然会出错，把点号后面的部分也做为了第一部分。为了解决这个问题，我们可以使用一个 ＜p＞ 标志将第二分部分开为下一段，如上例的“* ＜p＞show 方法的详细说明第一行 ....”。除此之外，我们也可以使用 ＜br＞ 来分隔。
　　第二部分是详细说明部分。该部分对属性或者方法进行详细的说明，在格式上没有什么特殊的要求，可以包含若干个点号。它在文档中的位置如下图所示：
　　　  
　　这部分文档在上例中相应的代码是：
　　* show 方法的简述.
　　* ＜p＞show 方法的详细说明第一行＜br＞
　　* show 方法的详细说明第二行
　　发现什么了？对了，简述也在其中。这一点要记住了，不要画蛇添足——在详细说明部分中再写一次简述哦！
　　第三部分是特殊说明部分。这部分包括版本说明、 参数 说明、返回值说明等。它在文档中的位置：
　　　  
　　第三部分在上例中相应的代码是 
　　* @ param  b true 表示显示，false 表示隐藏
　　* @return 没有返回值 
　　除了 @ param  和 @return 之外，还有其它的一些特殊标记，分别用于对类、属性和方法的说明……不要推我，我马上就说。
　　三. 使用  javadoc  标记
　　 javadoc  标记是插入文档注释中的特殊标记，它们用于标识代码中的特殊引用。 javadoc  标记由“@”及其后所跟的标记类型和专用注释引用组成。记住了，三个部分——@、标记类型、专用注释引用。不过我宁愿把它分成两部分：@ 和标记类型、专用注释引用。虽然 @ 和 标记类型之间有时可以用空格符分隔，但是我宁愿始终将它们紧挨着写，以减少出错机会。
　　 javadoc  标记有如下一些：
　　　  
　　下面详细说明各标记。
　　1. @see 的使用
　　@see 的句法有三种： 
　　@see 类名
　　@see #方法名或属性名
　　@see 类名#方法名或属性名
　　类名，可以根据需要只写出类名 (如 String) 或者写出类全名 (如 java.lang.String)。那么什么时候只需要写出类名，什么时候需要写出类全名呢？
　　如果 java 源文件中的 import 语句包含了的类，可以只写出类名，如果没有包含，则需要写出类全名。java.lang 也已经默认被包含了。这和 javac 编译 java 源文件时的规定一样，所以可以简单的用 javac 编译来判断，源程序中 javac 能找到的类， javadoc  也一定能找到；javac 找不到的类， javadoc  也找不到，这就需要使用类全名了。
　　方法名或者属性名，如果是属性名，则只需要写出属性名即可；如果是方法名，则需要写出方法名以及 参数 类型，没有 参数 的方法，需要写出一对括号。如
　　　  
　　有时也可以偷懒：假如上例中，没有 count 这一属性，那么参考方法 count() 就可以简写成 @see count。不过，为了 安全 起见，还是写全 @see count() 比较好。
　　@see 的第二个句法和第三个句法都是转向方法或者属性的参考，它们有什么区别呢？
　　第二 
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 Test Java Doc {
　　} 
　　生成文档的相关部分如图：
　　　  
　　从生成文档的图示中可以看出，两个 @author 语句都被编译，在文档中生成了作者列表。而两个 @version 语句中只有第一句被编译了，只生成了一个版本号。
　　从图上看，作者列表是以逗号分隔的，如果我想分行显示怎么办？另外，如果我想显示两个以上的版本号又该怎么办？
　　——我们可以将上述两条 @author 语句合为一句，把两个 @version 语句也合为一句：
　　@author Fancy＜br＞Bird
　　@version Version 1.00＜br＞Version 2.00
　　结果如图：
　　　  
　　我们这样做即达到了目的，又没有破坏规则。@author 之后的作者名和 @version 之后的版本号都可以是用户自己定义的任何 HTML 格式，所以我们可以使用 ＜br＞ 标记将其分行显示。同时，在一个 @version 中指明两个用 ＜br＞ 分隔的版本号，也没有破坏只显示第一个 @version 内容的规则。
　　3. 使用 @ param 、@return 和 @exception 说明方法
　　这三个标记都是只用于方法的。@ param  描述方法的 参数 ，@return 描述方法的返回值，@exception 描述方法可能抛出的异常。它们的句法如下：
　　@ param   参数 名  参数 说明
　　@return 返回值说明
　　@exception 异常类名 说明
　　每一个 @ param  只能描述方法的一个 参数 ，所以，如果方法需要多个 参数 ，就需要多次使用 @ param  来描述。
　　一个方法中只能用一个 @return，如果文档说明中列了多个 @return，则  javadoc  编译时会发出警告，且只有第一个 @return 在生成的文档中有效。
　　方法可能抛出的异常应当用 @exception 描述。由于一个方法可能抛出多个异常，所以可以有多个 @exception。每个 @exception 后面应有简述的异常类名，说明中应指出抛出异常的原因。需要注意的是，异常类名应该根据源文件的 import 语句确定是写出类名还是类全名。 　　示例如下：
　　public class Test Java Doc {
　　/**
　　* @ 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  的常用命令。
　　四.  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  fancy/Test.java fancy/Editor.java fancy/editor/ECommand.java fancy/editor/EDocument.java fancy/editor/EView.java
　　这是给出 java 源文件作为编译 参数 的方法，注意命令中指出的是文件路径，应该根据实际情况改变。也可以是给出包名作为编译 参数 ，如：
　　 javadoc  fancy fancy.editor
　　用浏览器打开生成文档的 index.html 文件即可发现两种方式编译结果的不同，如下图：
　　  
　　用第二条命令生成的文档被框架分成了三部分：包列表、类列表和类说明。在包列表中选择了某个包之后，类列表中就会列出该包中的所有类；在类列表中选择了某个类之后，类说明部分就会显示出该类的详细文档。而用第一条命令生成的文档只有两部分，类列表和类说明，没有包列表。这就是两种方式生成文档的最大区别了。
　　两种方式编译还有一点不同，
　　下面再来细说选项。
　　-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  就介绍完了。