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 标识。