javadoc - Java API 文档生成器
http://www.computersci.net/articles/jdk1.2/docs/tooldocs/win32/javadoc.html
简单示例
可以对整个包或单个类运行 javadoc。每个包名有一个相应的目录名。在下面的示例中,源文件位于
C:\home\src\java\awt\*java
。目的目录是C:\home\html
。建立包的文档
要建立包的文档,该包的源文件(
*.java
)必须位于一个与该包名字相同的目录中。如果包名由几个标识符组成(用点号分隔),则每个标识符代表一个不同的目录。因而,所有java.awt
类必须位于名为java\awt\
的目录中。可用如下两种方式之一运行 javadoc -- 通过改变目录(用cd
)或使用sourcepath
选项。不能使用通配符指定多个包。
- 情况 1- 换到包目录 - 换到全限定包的父目录。然后运行 run javadoc,并提供想要建立其文档的一个或多个包的名字:
C:> cd C:\home\src\ C:> javadoc -d C:\home\html java.awt java.awt.event- 情况 2 - 从任何目录 - 在这种情况下,当前目录是什么没有关系。运行 javadoc 时用
sourcepath
提供全限定包的父目录,并提供想要建立其文档的一个或多个包的名字:C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt java.awt.event这两种情况都将产生包
java.awt
和java.awt.event
中公共和保护类和接口的 HTML 格式文档,并将 HTML 文件保存在指定目的目录(C:\home\html
)中。因为要生成两个或多个包,所以文档具有三个框架 -- 包列表、类列表和主页。建立类的文档
要建立一个或多个源文件(
.java
)的文档,这些文件不必位于特定目录中。可以用如下两种方式之一运行 javadoc -- 通过改变目录(用cd
)或完全指定.java
文件的路径。选项-sourcepath
在建立源文件的文档时没有作用。可使用命令行通配符,例如星号(*),指定多个类。
- 情况 1 - 换到源目录 - 换到保存
.java
文件的目录。然后运行 javadoc,并提供想要建立其文档的一个或多个源文件名。C:> cd C:\home\src\java\awt C:> javadoc -d C:\home\html Button.java Canvas.java Graphics*.java该示例产生类
Button
、Canvas
和以Graphics
开头的类的 HTML 格式文档。因为是源文件而不是包名作为参数传递给 javadoc,所以文档具有两个框架 -- 类列表和主页。- 情况 2 - 改变到包的根目录 - 当要为相同根目录下不同子包中的单个源文件建立文档时,这是非常有用的。改变到包的根目录,并提供源文件相对于其根的路径。
C:> cd /home/src/ C:> javadoc -d /home/html java/awt/Button.java java/applet/Applet.java该示例产生类
Button
和Applet
的 HTML 格式文档。- 情况 3 - 从任何目录 - 在这种情况下,当前目录是什么没有关系。运行 javadoc,并提供想要建立其文档的
.java
文件的绝对路径(或相对于当前目录的相对路径)。C:> javadoc -d C:\home\html C:\home\src\java\awt\Button.java C:\home\src\java\awt\Graphics*.java该示例产生类
Button
和以Graphics
开头的类的 HTML 格式文档。建立包和类的文档
可同时建立整个包和单个类的文档。下面是一个混合前两个示例的示例。可使用
-sourcepath
指定包的路径但不作为单个类的路径。C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt C:\home\src\java\applet\Applet.java该示例生成包
java.awt
和类Applet
的 HTML 格式文档(Javadoc 从Applet.java
源文件中的包声明(如果有)中确定Applet
的包名)。
实际示例
Javadoc 有许多有用的选项,有些相对其他更为常用。下面是实际中我们用来在 Java 平台 API 上运行 javadoc 的命令,它使用了 makefile 变量(除了未列出所有要建文档的包之外)。
javadoc -sourcepath /jdk/src/share/classes \ /* 源文件路径 */ -d /jdk/build/api \ /* 目的目录 */ -use \ /* 添加“用法”文件 */ -splitIndex \ /* 分割索引 A-Z */ -windowtitle $(WINDOWTITLE) \ /* 添加窗口标题 */ -doctitle $(DOCTITLE) \ /* 添加文档标题 */ -header $(HEADER) \ /* 添加运行页眉文本 */ -bottom $(BOTTOM) \ /* 添加底部文本 */ -group $(GROUPCORE) \ /* 概述页的核心标题 */ -group $(GROUPEXT) \ /* 概述页的扩展标题 */ -overview overview-core.html \ /* 概述文本 */ -J-Xmx180m \ /* 180MB 内存 */ java.lang java.lang.reflect \ /* 要建立其文档的包 */ java.util java.io java.net \ java.applet WINDOWTITLE = 'Java 平台 1.2 最终 API 规范' DOCTITLE = 'Java<sup><font size="-2">TM</font></sup> Platform 1.2 Final API Specification' HEADER = '<b>Java Platform 1.2</b><br><font size="-1">Final</font>' BOTTOM = '<font size="-1"><a href="http://java.sun.com/cgi-bin/bugreport.cgi"> 提交 bug 或功能 </a><br><br>Java 是 Sun Microsystems , Inc 在美国和其他国家 的商标或注册商标。<br>Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. 保留所有权利。</font>' GROUPCORE = '"核心包" "java.*:com.sun.java.*:org.omg.*" GROUPEXT = '"扩展包" "javax.*"'如果省略
-windowtitle
选项,则 javadoc 将文档标题复制到窗口标题。-windowtitle
选项是没有必要的,除非文档标题包含 HTML 标记。如果像这里所做的一样省略
-footer
选项,则 javadoc 将页眉文本复制到脚注文本。其他重要的选项是
-classpath
和-link
。
Code Conventions for the JavaTM Programming Language
http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html