知识大全 JavaDoc，在 Java 的注释上做文章(下)

Posted 2022-07-20 知

篇首语：时人不识凌云木，直待凌云始道高。本文由小常识网(cha138.com)小编为大家整理，主要介绍了知识大全 JavaDoc，在 Java 的注释上做文章(下)相关的知识，希望对你有一定的参考价值。

JavaDoc，在 Java 的注释上做文章(下) 以下文字资料是由(全榜网网www.cha138.com)小编为大家搜集整理后发布的内容，让我们赶快一起来看一下吧！

　　使用 @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 java lang Exception throw when switch is 　　* @exception NullPointerException throw when parameter n is null　　*/　　public boolean fun(Integer n) throws Exception 　　switch (n intValue()) 　　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 下有两个包若干类如下　　fancy Editor　　fancy Test　　fancy editor ECommand　　fancy editor EDocument　　fancy editor EView　　这里有两个包 (fancy 和 fancy editor) 和个类那么编译时 (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　　用浏览器打开生成文档的 l 文件即可发现两种方式编译结果的不同如下图　　　　用第二条命令生成的文档被框架分成了三部分包列表类列表和类说明在包列表中选择了某个包之后类列表中就会列出该包中的所有类在类列表中选择了某个类之后类说明部分就会显示出该类的详细文档而用第一条命令生成的文档只有两部分类列表和类说明没有包列表这就是两种方式生成文档的最大区别了　　两种方式编译还有一点不同　　下面再来细说选项　　 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 就介绍完了 javadoc 真的能让我们在 Java 注释上做文章——生成开发文　　　　　　　　　　　　　　　　　　　　 cha138/Article/program/Java/JSP/201311/19745