对于Java注释我们主要了解两种
// 注释一行
/* */ 注释若干行
但还有第三种文档注释
/** */ 注释若干行并写入 javadoc 文档
通常这种注释的多行写法如下
/**
*
*
*/
很多人多忽视了这第三种注释那么这第三种注释有什么用？javadoc 又是什么东西？下面我们就谈谈
一 Java 文档和 Javadoc
Java 程序员都应该知道使用 JDK 开发最好的帮助信息就来自 SUN 发布的 Java 文档它分包分类详细的提供了各方法属性的帮助信息具有详细的类树信息索引信息等并提供了许多相关类之间的关系如继承实现接口引用等
Java 文档全是由一些 html 文件组织起来的在 SUM 的站点上可以下载它们的压缩包但是你肯定想不到这些文档我们可以自己生成——就此打住再吊一次胃口
安装了 JDK 之后安装目录下有一个 srcjar 文件或者 srczip 文件它们都是以 ZIP 格式压缩的可以使用 WinZip 解压解压之后我们就可以看到分目录放的全是 java 文件是了这些就是 Java 运行类的源码了非常完整连注释都写得一清二楚……不过怎么看这些注释都有点似曾相识的感觉？
这就不奇怪了我们的迷底也快要揭开了如果你仔细对比一下 java 源文件中的文档注释 (/** */) 和 Java 文档的内容你会发现它们就是一样的Java 文档只是还在格式和排版上下了些功夫再仔细一点你会发现 java 源文件中的注释还带有 HTML 标识如 ＜B＞＜BR＞＜Code＞ 等在 Java 文档中该出现这些标识的地方已经按标识的的定义进行了排版
终于真像大白了原来 Java 文档是来自这些注释难怪这些注释叫做文档注释呢！不过是什么工具把这些注释变成文档的呢？
是该请出 javadoc 的时候了在 JDK 的 bin 目录下你可以找到 javadoc如果是 Windows 下的 JDK它的文件名为 javadocexe使用 javdoc 编译 java 源文件时它会读出 java 源文件中的文档注释并按照一定的规则与 Java 源程序一起进行编译生成文档
介绍 javadoc 的编译命令之前还是先了解一下文档注释的格式吧不过为了能够编译下面提到的若干例子这里先介绍一条 javadoc 命令
javadoc d 文档存放目录 author version 源文件名java
这条命令编译一个名为 源文件名java的 java 源文件并将生成的文档存放在文档存放目录指定的目录下生成的文档中 l 就是文档的首页author 和 version 两上选项可以省略
二 文档注释的格式
文档注释可以用于对类属性方法等进行说明写文档注释时除了需要使用 /** */ 限定之外还需要注意注释内部的一些细节问题
文档和文档注释的格式化
生成的文档是 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 javalang*;
/** commnet for class */
public class Test { }
// 此例为正确的例子
这个文档注释将生成正确的文档但只需要改变其中两行的位置变成下例就会出错
/** commnet for class */
import javalang*;
public class Test { }
// 此例为错误的例子
这个例子只把上例的 import 语句和文档注释部分交换了位置结果却大不相同——生成的文档中根本就找不到上述注释的内容了原因何在？
/** commnet for class */是对 class Test 的说明把它放在public class Test { }之前时其后紧接着 class Test符合规则所以生成的文档正确但是把它和import javalang*;调换了位置后其后紧接的就是不 class Test 了而是一个 import 语句由于文档注释只能说明类属性和方法import 语句不在此列所以这个文档注释就被当作错误说明省略掉了
文档注释的三部分
根据在文档中显示的效果文档注释分为三部分先举例如下以便说明
/**
* show 方法的简述
* ＜p＞show 方法的详细说明第一行＜br＞
* show 方法的详细说明第二行
* @param b true 表示显示false 表示隐藏
* @return 没有返回值
*/
public void show(boolean b) {
frameshow(b);
}
第一部分是简述文档中对于属性和方法都是先有一个列表然后才在后面一个一个的详细的说明列表中属性名或者方法名后面那段说明就是简述如下图中被红框框选的部分
简述部分写在一段文档注释的最前面第一个点号 () 之前 (包括点号)换句话说就是用第一个点号分隔文档注释之前是简述之后是第二部分和第三部分如上例中的 * show 方法的简述
有时即使正确地以一个点号作为分隔javadoc 仍然会出错把点号后面的部分也做为了第一部分为了解决这个问题我们可以使用一个 ＜p＞ 标志将第二分部分开为下一段如上例的* ＜p＞show 方法的详细说明第一行 除此之外我们也可以使用 ＜br＞ 来分隔
第二部分是详细说明部分该部分对属性或者方法进行详细的说明在格式上没有什么特殊的要求可以包含若干个点号它在文档中的位置如下图所示
这部分文档在上例中相应的代码是
* show 方法的简述
* ＜p＞show 方法的详细说明第一行＜br＞
* show 方法的详细说明第二行
发现什么了？对了简述也在其中这一点要记住了不要画蛇添足——在详细说明部分中再写一次简述哦！
第三部分是特殊说明部分这部分包括版本说明参数说明返回值说明等它在文档中的位置
第三部分在上例中相应的代码是
* @param b true 表示显示false 表示隐藏
* @return 没有返回值
除了 @param 和 @return 之外还有其它的一些特殊标记分别用于对类属性和方法的说明……不要推我我马上就说
三 使用 javadoc 标记
javadoc 标记是插入文档注释中的特殊标记它们用于标识代码中的特殊引用javadoc 标记由@及其后所跟的标记类型和专用注释引用组成记住了三个部分——@标记类型专用注释引用不过我宁愿把它分成两部分@ 和标记类型专用注释引用虽然 @ 和 标记类型之间有时可以用空格符分隔但是我宁愿始终将它们紧挨着写以减少出错机会
javadoc 标记有如下一些
下面详细说明各标记
@see 的使用
@see 的句法有三种
@see 类名
@see #方法名或属性名
@see 类名#方法名或属性名
类名可以根据需要只写出类名 (如 String) 或者写出类全名 (如 javalangString)那么什么时候只需要写出类名什么时候需要写出类全名呢？
如果 java 源文件中的 import 语句包含了的类可以只写出类名如果没有包含则需要写出类全名javalang 也已经默认被包含了这和 javac 编译 java 源文件时的规定一样所以可以简单的用 javac 编译来判断源程序中 javac 能找到的类javadoc 也一定能找到javac 找不到的类javadoc 也找不到这就需要使用类全名了
方法名或者属性名如果是属性名则只需要写出属性名即可如果是方法名则需要写出方法名以及参数类型没有参数的方法需要写出一对括号如
有时也可以偷懒假如上例中没有 count 这一属性那么参考方法 count() 就可以简写成 @see count不过为了安全起见还是写全 @see count() 比较好
@see 的第二个句法和第三个句法都是转向方法或者属性的参考它们有什么区别呢？
第二
