在软件项目管理过程中,如何保证程序代码与软件技术文档一致可以说是最令人头疼的一件事情了。不管是先修改代码,还是先修改文档,对各种记录的管理都是一件麻烦事。而且,二者在改动上的一致性、实时性还很难得到保证。令人高兴的是Java平台的设计者充分考虑到了这一点,他们十分"体贴"地为Java开发者们带来一个文档管理工具--javadoc。
javadoc利用Java编译程序javac对程序代码源文件中的声明和文档注释进行语法分析,并在默认情况下生成一组HTML文档来描述类、内部类、接口、构造函数、方法和域。不过在运行过程中,它也使用了Java平台的环境变量classpath来确定类查找路径。这样当涉及类和内部类的有关描述时,是否正确地设置了classpath变量可能会影响到javadoc命令是否可以完全成功执行。
javadoc产生的默认文件列表如下:
基本页面文件:
calssname.html 类或者接口描述文件,一个文件对应一个类或者接口
package-summary.html 包摘要文件,一个文件对应一个包
overview-summary.html 总的摘要文件
交叉引用页面文件:
overview-tree.html 所有包的类层次页面
package-tree.html 某个包的类层次页面
package-use.html 包用法页面
class-use\classname.html 类用法页面
deprecated-list.html 不鼓励使用的方法的页面
serialized-form.html 序列化页面
index-*.html 索引文件
支持文件:
help-doc.html 帮助文件
index.html 引导页面,是整个文档的入口
*-frame.html 框架文件
stylesheet.css 样式表文件
doc-files目录 保存与HTML相关的一些杂文件。例如图片文件等。
javadoc的命令行语法如下:
javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]
参数可以按照任意顺序排列。下面分别就这些参数和相关的一些内容进行说明:
Packagenames 包列表。这个选项可以是一系列的包名(用空格隔开),例如java.lang java.lang.reflect
java.awt。不过,因为javadoc不递归作用于子包,不允许对包名使用通配符;所以你必须显示地列出希望建立文档的每一个包。
Sourcefiles 源文件列表。这个选项可以是一系列的源文件名(用空格隔开),可以使用通配符。javadoc允许四种源文件:类源代码文件、包描述文件、总体概述文件、其他杂文件。
◇ 类源代码文件:类或者接口的源代码文件。
◇ 包描述文件:每一个包都可以有自己的包描述文件。包描述文件的名称必须是"package.html",与包的.java文件放置在一起。包描述文件的内容通常是使用HTML标记写的文档。javadoc执行时将自动寻找包描述文件。如果找到,javadoc将首先对描述文件中之间的内容进行处理,然后把处理结果放到该包的Package
Summary页面中,最后把包描述文件的第一句(紧靠)放到输出的Overview summary页面中,并在语句前面加上该包的包名。
◇ 总体概述文件:javadoc可以创建一个总体概述文件描述整个应用或者所有包。总体概述文件可以被任意命名,也可以放置到任意位置。-overview选项可以指示总体概述文件的路径和名称。总体概述文件的内容是使用HTML标记写的文档。javadoc在执行的时候,如果发现-overview选项,那么它将首先对文件中之间的内容进行处理;然后把处理后的结果放到输出的Overview
summary 页面的底部;最后把总体概述文件中的第一句放到输出的Overview summary页面的顶部。
◇ 其他杂文件:这些文件通常是指与javadoc输出的HTML文件相关的一些图片文件、Java源代码文件(.java)、Java程序(.class)、Java小程序(Applets)、HTML文件。这些文件必须放在doc-files目录中。每一个包都可以有自己的doc-files目录。举个例子,你希望在java.awt.Button的HTML文档中使用一幅按钮的图片(Button.gif)。首先,你必须把图片文件放到C:\user\src\java\awt\doc-files\中;然后在Button.java文件中加入下面注释