使用 @author@version 说明类
这两个标记分别用于指明类的作者和版本缺省情况下 javadoc 将其忽略但命令行开关 author 和 version 可以修改这个功能使其包含的信息被输出这两个标记的句法如下
@author 作者名
@version 版本号
其中@author 可以多次使用以指明多个作者生成的文档中每个作者之间使用逗号 () 隔开@version 也可以使用多次只有第一次有效生成的文档中只会显示第一次使用 @version 指明的版本号如下例
/**
* @author Fancy
* @author Bird
* @version Version
* @version Version
*/
public class TestJavaDoc {
}
生成文档的相关部分如图
从生成文档的图示中可以看出两个 @author 语句都被编译在文档中生成了作者列表而两个 @version 语句中只有第一句被编译了只生成了一个版本号
从图上看作者列表是以逗号分隔的如果我想分行显示怎么办？另外如果我想显示两个以上的版本号又该怎么办？
——我们可以将上述两条 @author 语句合为一句把两个 @version 语句也合为一句
@author Fancy＜br＞Bird
@version Version ＜br＞Version
结果如图
我们这样做即达到了目的又没有破坏规则@author 之后的作者名和 @version 之后的版本号都可以是用户自己定义的任何 HTML 格式所以我们可以使用 ＜br＞ 标记将其分行显示同时在一个 @version 中指明两个用 ＜br＞ 分隔的版本号也没有破坏只显示第一个 @version 内容的规则
使用 @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 javalangException throw when switch is
* @exception NullPointerException throw when parameter n is null
*/
public boolean fun(Integer n) throws Exception {
switch (nintValue()) {
case :
break;
case :
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 下有两个包若干类如下
fancyEditor
fancyTest
fancyeditorECommand
fancyeditorEDocument
fancyeditorEView
这里有两个包 (fancy 和 fancyeditor) 和 个类那么编译时 (Windows 环境) 可以使用如下 javadoc 命令
javadoc fancy\Testjava fancy\Editorjava fancy\editor\ECommandjava fancy\editor\EDocumentjava fancy\editor\EViewjava
这是给出 java 源文件作为编译参数的方法注意命令中指出的是文件路径应该根据实际情况改变也可以是给出包名作为编译参数如
javadoc fancy fancyeditor
用浏览器打开生成文档的 l 文件即可发现两种方式编译结果的不同如下图
用第二条命令生成的文档被框架分成了三部分包列表类列表和类说明在包列表中选择了某个包之后类列表中就会列出该包中的所有类在类列表中选择了某个类之后类说明部分就会显示出该类的详细文档而用第一条命令生成的文档只有两部分类列表和类说明没有包列表这就是两种方式生成文档的最大区别了
两种方式编译还有一点不同
下面再来细说选项
publicprotectedpackageprivate 四个选项只需要任选其一即可它们指定的显示类成员的程度它们显示的成员多少是一个包含的关系如下表
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 就介绍完了javadoc 真的能让我们在 Java 注释上做文章——生成开发文
