4.4　JavaDoc文档

4.4.1　JavaDoc介绍

Java程序员都应该知道使用JDK开发，最好的帮助信息就来自Sun发布的Java文档。它分包、分类详细地提供各方法、属性的帮助信息，具有详细的类树信息、索引信息等，并提供许多相关类之间的关系，例如，继承、实现接口、引用等，是Java编程非常好的帮助文件编写工具。

4.4.2　JavaDoc标记

JavaDoc注释由JavaDoc标签和描述性文本组成，开发人员可以为类、接口添加注释，也可为构造函数、值域、方法等类中的元素添加注释。4.2.3节注释规范中已详细说明如何注释。本节仅针对具体标记详细说明如下。

1. 标记列表

@author对类的说明，标明开发该类模块的作者。

@version对类的说明，标明该类模块的版本。

@see对类、属性、方法的说明，参考转向，也就是相关主题。

@param对方法的说明，对方法中某参数的说明。

@return对方法的说明，对方法返回值的说明。

@exception对方法的说明，对方法可能抛出的异常进行说明。

{@link包.类#成员标签}链接到某个特定的成员对应的文档中，包括包、类、接口、值域、构造函数、方法。

{@value}当对常量进行注释时，如果想将其值包含在文档中，则通过该标签来引用常量，静态值域。

2. 参数详细解释

1）@see的3种句法

     @see类名
     @see#方法名或属性名
     @see类名#方法名或属性名

第一个句法主要说明类名即可。

第二个句法中没有指出类名，则默认为当前类。所以它定义的参考，都转向本类中的属性或者方法。而第三个句法中指出了类名，则还可以转向其他类的属性或者方法。

2）使用@author和@version说明类

这两个标记分别用于指明类的作者和版本。默认情况下，JavaDoc将其忽略，但命令行开关-author和-version可以修改这个功能，使其包含的信息被输出。这两个标记的句法如下。

     @author作者名
     @version版本号

其中，@author可以多次使用，以指明多个作者，生成的文档中每个作者之间使用逗号（，）隔开。@version也可以使用多次，只有第一次有效，生成的文档中只会显示第一次使用@version指明的版本号。

3）使用@param、@return和@exception说明方法

这3个标记都是只用于方法的。@param描述方法的参数，@return描述方法的返回值，@exception描述方法可能抛出的异常。它们的句法如下。

     @param参数名,参数说明
     @return返回值说明
     @exception异常类名说明

每一个@param只能描述方法的一个参数，所以，如果方法需要多个参数，就需要多次使用@param来描述。

一个方法中只能用一个@return，如果文档说明中列了多个@return，则JavaDoc编译时会发出警告，且只有第一个@return在生成的文档中有效。

方法可能抛出的异常应当用@exception描述。由于一个方法可能抛出多个异常，所以可以有多个@exception。每个@exception后面应有简述的异常类名，说明中应指出抛出异常的原因。需要注意的是，异常类名应该根据源文件的import语句确定是写出类名还是类全名。

4.4.3　JavaDoc命令的用法

1. JavaDoc命令

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

     javadoc[options][packagenames][sourcefiles]

选项options说明如下：

-public仅显示public类和成员；

-protected显示protected/public类和成员（默认）；

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

-private显示所有类和成员；

-d<directory>输出文件的目标目录；

-version包含@version段；

-author包含@author段；

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

     -windowtitle <text >  文档的浏览器窗口标题。

2. 参数详细解释

-d选项允许定义输出目录。如果不用-d定义输出目录，生成的文档文件会放在当前目录下。-d选项的用法如下：

     -d目录名

目录名为必填项，也就是说，如果使用了-d参数，就一定要为它指定一个目录。这个目录必须已经存在；如果还不存在，需在运行JavaDoc之前创建该目录。

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

-splitindex选项将索引分为每个字母对应一个文件。默认情况下，索引文件只有一个，且该文件中包含所有索引内容。当然生成文档内容不多的时候，这样做非常合适；但是，如果文档内容非常多，这个索引文件将包含非常多的内容，显得过于庞大。使用-splitindex会把索引文件按各索引项的第一个字母进行分类，每个字母对应一个文件，这样，就减轻了一个索引文件的负担。

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

     -windowtitle标题

标题是一串没有包含空格的文本，因为空格符是用于分隔各参数的，所以不能包含空格。同-d类似，如果指定了-windowtitle选项，则必须指定标题文本。