javadoc用法 - 达人(未来)

2004/08/20 | javadoc用法
类别(java) | 评论(0) | 阅读(1578) | 发表于 22:33: 结构
javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]

参数可按任意次序排列。

options
命令行选项，如本文档中所指定。要了解 javadoc 选项的典型用法，参见实际示例。
packagenames
一系列包的名字，用空格分隔，例如 java.lang java.lang.reflect java.awt。必须分别指定想要为之建立文档的每一个包。Javadoc 不递归地作用于子包。不允许使用通配符，如（*）。参见示例 - 建立包的文档
sourcefiles
一系列源文件名，用空格分隔。源文件名可包括路径和通配符如（*）。例如：Button.java /home/src/java/awt/Graphics*.java 参见示例 - 建立类的文件。还可混合包名和源文件，如示例 - 建立包和类的文档中所示。
@files
以任何次序包含包名和源文件的一个或多个文件。

说明
Javadoc 解析 Java 源文件中的声明和文档注释，并产生相应的 HTML 页（缺省），描述公有类、保护类、内部类、接口、构造函数、方法和域。

可对整个包、单个源文件或二者运行 Javadoc。在第一种情况中，将一系列包名作为参数传递给 javadoc。在第二种情况中，传递一系列源（.java）文件名。在本文档最后给出了示例。

在实现时，Javadoc 要求且依赖于 java 编译器完成其工作。Javadoc 调用部分 javac 编译声明部分，忽略成员实现。它建立类的内容丰富的内部表示，包括类层次和“使用”关系，然后从中生成 HTML。Javadoc 还从源代码的文档注释中获得用户提供的文档。

实际上，Javadoc 将在不带方法体的纯 stub 文件的 .java 源文件上运行。这意味着可以创建 API 的最早期阶段，在编写任何代码之前，就可编写文档注释并运行 Javadoc。

依赖编译器可以确保 HTML 输出完全对应于实际实现，这些实现可能有赖于隐式的（而非显式的）源代码。例如，Javadoc 将建立在 .class 文件中存在但在源代码中不存在的缺省构造函数（Java 语言规范的第 8.6.7 节）的文档。

当 Javadoc 建立其内部文档结构时，它将加载所有引用的类。由于这一点，Javadoc 必须能查找到所有引用的类，包括引导类、扩展类和用户类。有关详细信息，参见如何查找类。一般而言，所创建的类必须加载为扩展或位于 Javadoc 的类路径中。

Javadoc Doclets
可使用 doclets 自定义 Javadoc 输出的内容和格式。Javadoc 具有一个缺省的“内嵌”doclet，叫作标准 doclet，它生成 HTML-格式的 API 文档。用户可修改或扩展标准 doclet，或编写自己的 doclet 以生成 HTML、XML、MIF、RTF 或想要的任何输出格式。关于 doclets 及其用法的信息位于下列位置：

Javadoc Doclets
-doclet 命令行选项
当没有用 -doclet 命令行选项指定自定义 doclet 时，Javadoc 将使用缺省的标准 doclet。不管使用哪个 doclet，javadoc 工具都有几个命令行选项可用。标准 doclet 还添加了额外的命令行选项集。二个选项集都将在下面的选项一节中介绍。

相关文档
有关 Javadoc 1.2 中增强功能的详细信息，参见 Javadoc 增强。
有关常问问题的答案、关于 Javadoc 相关工具的信息以及 bug 的解决方案，参见 Javadoc FAQ。
有关如何编写文档注释的信息，参见如何为 Javadoc 编写文档注释。

术语
在 Javadoc 环境中，有些术语具有特定的意义：

生成的文档
由 javadoc 工具根据 Java 源代码中文档注释生成的文档。缺省的生成文档是 HTML 格式，并由标准 doclet 生成。

名字
Java 语言中的名字，通常为包、类、接口、域、构造函数或方法的名字。名字可以是完全限定的，例如 java.lang.String.equals(java.lang.Object)，也可是部分限定的，例如 equals(Object)。

带文档的类
在 javadoc 运行期间为之生成了全部文档的类和接口。要生成文档，源文件必须可用，并且其源文件名或包名必须传递到 javadoc 命令中。我们还将这些类称为在 javadoc 运行中包含的类，或包含的类。

引用类
在带文档的类和接口的定义（实现）中显式引用的类和接口。引用的例子包括返回类型、参数类型、强制转换类型、已实现接口、导入类，等等。在文档注释（例如 @see 标记）中引用的类不算作引用类。当 Javadoc 运行时，它将 javadoc 引导类路径和类路径中所有的引用类加载到内存中（对于没有找到的引用类，Javadoc 将显示“类未找到”警告信息）。 Javadoc 可从类文件中获得足够的信息，以确定其存在性及其成员的全限定名字。

外部引用类
在 javadoc 运行期间没有生成其文档的引用类。也就是说，这些类对于该次 javadoc 运行是外部的。文档中名字到这些类的链接称为外部引用或外部链接。例如，如果仅对 java.awt 包运行 javadoc，则 java.lang 中的任何类（如 Object）都是外部引用类。可使用 -link 选项链接外部引用类。

源文件
Javadoc 将根据四种不同的“源”文件生成输出： Java 语言源文件（.java）、包注释文件、概述注释文件和其他未处理文件。下面介绍了后三种类型。

包注释文件
每个包具有它自己的文档注释，保存在其自己的“源”文件中，Javadoc 将把它合并到生成的包概览页中。通常可在这个注释中包括适用于整个包的任何文档。

要创建包注释文件，必须将它命名为 package.html 并将它与 .java 文件一起放在源树中的包目录中。Javadoc 将自动在该位置查找该文件名。注意该文件名对于所有包都是相同的。

包注释文件的内容是一个大文档注释，用 HTML 编写，像所有其他注释一样，但有一个例外：文档注释不应该包括注释分隔符 /** 和 */ 或前导星号。在编写注释时，第一句应该是关于包的概览，并且在 <body> 和第一句之间不应该插入任何标题或其他文本。可包括 package 标记；与所有文档注释一样，除了 {@link} 之外的所有标记都应该位于描述之后。如果添加 @see 标记，则它必须是全限定名字。

当 Javadoc 运行时，它将自动查找该文件；如果找到，则 Javadoc 做下列事情：

复制 <body> 和 </body> 标记之间的全部内容以进行处理。
处理存在的任何包标记。
在它生成的包概览页底部插入处理后的文本，例如包概览。
将包注释的第一句复制到包概览页和概述页（例如概述概览）的顶部。确定语句结尾用的规则相同确定类和成员描述第一个语句的相同规则确定。

概述注释文件
每个要为之建立文档的应用程序或包集可以有它自己的概述文档注释，保存在其自己的“源”文件中，Javadoc 将把它合并到生成的概述页中。在该注释中通常可包括适用于整个应用程序或包集的任何文档。

要创建概述注释文件，可将该文件命名为想要的任何名字（通常为 overview.html）并将它放置在任何地方（通常位于源树的最顶层中）。注意对于相同源文件集可有多个概述注释文件，以用于对不同包集多次运行 javadoc。例如，如果 java.applet 包的源文件包含在 C:\user\src\java\applet 目录中，则可创建概述注释文件 C:\user\src\overview.html。

概述注释文件的内容是一个大文档注释，用 HTML 编写，与前面介绍的包注释文件类似。有关详细内容，参见描述。在编写注释时，要重新循环，第一句应该是关于应用程序或包集的概览，并且在 <body> 和第一句之间不要插入标题或任何其他文本。可包括概述标记；与所有文档注释一样，除了 {@link} 之外的所有标记都就位于描述之后。如果添加 @see 标记，则它必须是全限定名字。

当运行 Javadoc 时，可用 -overview 选项指定概述注释文件。然后将以与包注释文件类似的方法处理该文件。

复制 <body> 和 </body> 标记之间的全部内容以进行处理。
处理存在任何概述标记。
将处理过后的文本插入到生成的概述页（例如概述概览）的底部。
将概述注释的第一句复制到概述概览页的顶部。

其他未处理文件
还可在源文件中包括想要 Javadoc 复制到目的目录中的任何其他文件。这通常包括图形文件、示例 Java 源文件（.java）和类文件（.class）以及其内容远超过常规 Java 源文件文档注释的独立 HTML 文件。

要包括未处理文件，请将它们放入一个叫作 doc-files 的目录中，它可以是任何包目录的子目录。每个包可以有使用一个这种子目录。例如，如果想要在 java.awt.Button 类文档中包含按钮图像 button.gif，则可将该文件放入 /home/user/src/java/awt/doc-files/ 目录中。所有到未处理文件的链接都必须是硬编码的，因为 Javadoc 不查看这些文件 -- 它只是将目录及其全部内容复制到目的地。例如，Button.java 文档注释中的链接可能类似如下：

/**
* 该按钮类似如下：
* <img src="doc-files/Button.gif">
*/

生成的文件
缺省地，javadoc 使用标准 doclet 生成 HTML 格式文档。该 doclet 生成下列类型的文件（其中每个 HTML “页”相应于一个单独的文件）。注意 javadoc 生成具有二种名字的文件：用类/接口命名的文件，和不用类/接口命名的文件（例如 package-summary.html）。后一组中的文件包括下划线（以防止与前一组中的文件名冲突）。

基本内容页

为生成其文档的每个类或接口生成类或接口页（classname.html）。
为生成其文档的每个包生成包页（package-summary.html）。Javadoc 将在其中包含源目录树中包目录中的 package.html 文件中提供的任何 HTML 文本。
整个包集的概述页（overview-summary.html）。它是生成的文档的首页。Javadoc 将在其中包含用 -overview 选项指定的文件中提供的任何 HTML 文本。（注意在有些情况下未生成概述页，详情参见 Javadoc 输出。）
交叉参考页

整个包集的类层次页（overview-tree.html）。要查看它，可以单击导航栏上的“概述”，然后单击“树”。
整个包的类层次页（package-tree.html）。要查看它，可转到特定包、类或接口页；单击“树”显示该包的层次。
每个包的“用法”页（package-use.html）和每个类和接口的单独页（class-use/classname.html）。该页描述了使用给定类、接口或包的任何部分的包、类、方法、构造函数和域。给定一个类或接口 A，其“用法”页包括 A 的子类、声明为 A 的域、返回 A 的方法以及具有 A 类型参数的方法和构造函数。要访问该页，可首先转到包、类或接口，然后在导航栏中单击“用法”链接。
不鼓励使用的 API 页（deprecated-list.html），列出所有不鼓励使用的名字。（通常由于改进的原因不推荐使用不鼓励使用的名字，并提供了替代的名字。不鼓励使用的 API 在未来的实现中可能删除。）
序列化形式页（serialized-form.html），提供关于可序列化或可外部化类的信息。每个这种类具有其序列化域和方法的描述。该信息对于重实现人员有用，使用 API 的开发人员一般不感兴趣。尽管在导航栏中没有其链接，但是可通过转到任何序列化类并单击类描述的“参见”部分中的“序列化形式”，获得该信息。
所有类、接口、构造函数、域及方法名的索引（index-*.html），按字母次序排列。它为 Unicode 进行了国际化，并可生成为单个文件或为每个开始字符（例如英语中的 A - Z）生成一个单独的文件。
支持文件

帮助页（help-doc.html），它描述导航栏和上述各页。可使用 -helpfile 用自己的自定义帮助文件覆盖缺省帮助文件。
index.html 文件，创建用于显示的 HTML 框架。加载该文件可以用框架显示头版。该文件本身不包含文本内容。
包含包、类和接口列表的几个框架文件（*-frame.html），在显示 HTML 框架时使用。
包列表文件（package-list），通过 -link 和 -linkoffline 选项使用。它是文本文件，而不是 HTML 文件，并且不能通过任何链接到达。
样式表单文件（stylesheet.css），它用于控制生成页面上的颜色数、字体、字体大小、字体样式和定位。
HTML 框架

Javadoc 将生成两个或三个 HTML 框架，如下图中所示。当将源文件（*.java）或单个包名作为参数传递到 javadoc 命令中时，它将仅在左边栏中创建一个框架（C） -- 类列表。当给 javadoc 传递两个或多个包名时，它将创建第三个框架（P）（列出所有包）以及一个概述页（Detail）。可通过在“无框架”链接上单击或在 overview-summary.html 进入，绕过框架。

如果您不熟悉 HTML 框架，则应该记住框架可具有焦点，以进行打印或滚动。要使框架具有焦点，可在其上单击。然后在许多浏览器中，箭头键和翻页键将滚动该框架，而打印菜单命令将打印它。

------------ ------------
|C| Detail | |P| Detail |
| | | | | |
| | | |-| |
| | | |C| |
| | | | | |
| | | | | |
------------ ------------
javadoc *.java javadoc java.lang java.awt

根据是否想要 HTML 框架，可加载下列两个文件之一作为开始页：

index.html（需要框架）
overview-summary.html（不需要框架）

生成的文件结构

生成的类和接口按与 Java 源文件和类文件相同的目录层次组织。该结构是每个子包一个目录。

例如，为 java.applet.Applet 类生成的文档将位于 java\applet\Applet.html。java.applet 包的文件结构也是一样，假定目的目录命名为 apidocs。如前所述，包含词“frame”的所有文件将出现在左上框架或左下框架中。所有其他 HTML 文件出现在右边框架中。

注意 - 目录用粗体显示。星号（*）表示当 javadoc 的参数为源文件（*.java）而不是包名时省略的文件和目录。另外当参数为源文件名时，将创建 package-list 但是它为空。文档文件目录将不出现在目的地中，除非它在源目录树中存在。

apidocs 顶级目录
index.html 建立 HTML 框架的初始页
* overview-summary.html 列出带第一句概览的所有包
overview-tree.html 列出所有包的类层次
deprecated-list.html 列出所有包中不鼓励使用的 API
serialized-form.html 列出所有包的序列化形式
* overview-frame.html 列出所有包，用于左上框架
allclasses-frame.html 列出所有包的全部类，用于左下框架中
help-doc.html 列出如何组织这些页的用户帮助
index-all.html 未用 -splitindex 选项创建的缺省索引
index-files 用 -splitindex 选项创建的目录
index-<number>.html 用 -splitindex 选项创建的索引文件
package-list 列出包名，仅用于解析外部引用
stylesheet.css HTML 样式表单，用于定义字体、颜色和位置
java 子包目录
applet 子包目录
Applet.html Applet 类页
AppletContext.html AppletContext 接口页
AppletStub.html AppletStub 接口页
AudioClip.html AudioClip 接口页
* package-summary.html 列出带首句概览的类
* package-frame.html 列出该包中的类，用于左下框架
* package-tree.html 列出该包的类层次
package-use 列出使用该包的地方
doc-files 保存图像和示例文件的目录
class-use 保存 API 用法页的目录
Applet.html Applet 类用法页
AppletContext.html AppletContext 接口用法页
AppletStub.html AppletStub 接口用法页
AudioClip.html AudioClip 接口用法页

文档注释

注释源代码
可以在源代码中任何实体（类、接口、方法、构造函数或域）声明的前面包括文档注释。它们也称为 Javadoc 注释，并且文件必须用 HTML 编写，它们应使用 HTML 实体并可使用 HTML 标记。用户可使用自己浏览器支持的任何 HTML 版本；我们编写的标准 doclet 可在其它地方（文档注释外部）生成 HTML 3.2-兼容代码，其中包括级联样式表单和框架（由于使用框架集，我们在每个生成文件前面添加了“HTML 4.0”）。

例如，小于 (<) 和大于 (>) 符号的实体应该写为 < 和 >。类似地，与符号（&）应该写为 &。在下面的示例中显示了粗体 HTML 标记 。

下面是文档注释：

/**
* 这是 doc 注释。
* @see java.lang.Object
*/

文档注释由开始注释的字符 /** 和结束注释的字符 */ 之间的字符组成。文本分成一行或多行。当 javadoc 解析文档注释时，将去掉每行中的前导星号（*）；初始星号（*）字符前面的空格和制表字符也丢弃。如果省略一行上的前导星号，则所有前导空格将被去除。（在某种程度上，可以忽略前导星号。由于省略前导星号导致问题的一种情况是用 <pre> 标记格式化多行的缩进时，例如样本代码所示。没有前导星号，生成文档中的缩进将丢失，因为前导空格被删除。）

每个文档注释的首句应该为概览名，包含所声明实体的完整简要描述。该语句在第一个句号处结束后跟空格、制表或行结束符，或在第一个标记处结束。Javadoc 将首句复制到 HTML 页顶部的成员概览中。

文档注释只有在位于类、接口、构造函数、方法或域声明前面才能被识别。每个声明只有一个文档注释为 Javadoc 工具所识别。

当在文档注释中嵌入 HTML 标记时，不应使用 HTML 标题标记例如 <H1> 和 <H2>，因为 Javadoc 创建完全结构化的文档，而这些标记将会干扰所生成文档的格式。

以字符 @ 开始的第一行文档注释将结束描述并开始标记段落部分。上例中的 @see 标记就是这种标记段落。

有关文档注释的规范，参见 James Gosling、Bill Joy 和 Guy Steele 所著书籍 Java 语言规范中的第 18 章“文档注释”。

JAVADOC 标记
Javadoc 解析 Java 文档注释中嵌入的特殊标记。这些文档标记可帮助自动从源代码生成完整的格式化 API。标记用“at”符号（@）开头，并区分大小写 -- 必须按照正确大小写字母输入它们。标记必须从一行的开头开始（位于任何前导空格和可选星号之后），否则它将被视为普通文本。按规定应将相同名字的标记放在一起。例如，将所有 @see 标记放在一起。

有关我们将在未来版本中引入的标记的信息，参见提议标记。

当前标记有：

标记引入该标记的 JDK 版本
@author 1.0
@deprecated 1.0
@exception 1.0
{@link} 1.2
@param 1.0
@return 1.0
@see 1.0
@serial 1.2
@serialData 1.2
@serialField 1.2
@since 1.1
@throws 1.2
@version 1.0

@author name-text
当使用 -author 选项时，用指定的 name-text 在生成文档中添加“Author”项。文档注释可包含多个 @author 标记。可以对每个 @author 指定一个或多个名字。在前一种情况中，Javadoc 将在名字之间插入逗号（,）和空格。在后一种情况下，将全部文本复制到生成文档中而不进行解析。如果想要用逗号以外的本地化名字分隔符，则应每行使用这个名字。

@deprecated deprecated-text
添加注释，指示不应再使用该 API（尽管它仍可用）。Javadoc 将 deprecated-text 移动到描述前面，用斜体显示，并在它前面添加粗体警告： “不鼓励使用”。
deprecated-text 的首句至少应该告诉用户什么时候开始不鼓励使用该 API 及使用什么替代它。Javadoc 仅将首句复制到概览部分和索引中。后面的语句还可解释为什么不鼓励使用它。还应包括一个指向替代 API 的 {@link} 标记（对于 Javadoc 1.2 或更新版本）：

对于 Javadoc 1.2，使用 {@link} 标记。这将在需要的地方创建内嵌链接。例如：
/**
* @deprecated 在 JDK 1.1 中，被 {@link #setBounds(int,int,int,int)} 取代。
*/

对于 Javadoc 1.1，标准格式是为每个 @deprecated 标记创建 @see 标记（它不能内嵌）。
有关不鼓励使用的信息，参见 @deprecated 标记。

@exception class-name description
@exception 标记是 @throws 的同义标记。

{@link name label}
插入指向指定 name 的内嵌链接。该标记中 name 和 label 的语法与 @see 标记完全相同，如下所述，但是它产生内嵌链接而不是在“参见”部分中放置链接。该标记用花括号开始并用花括号结束，以使它区别于其他内嵌文本。如果在标签内需要使用“}”，则请使用 HTML 实体表示法 }
对于一个语句中所允许的 {@link} 标记数目没有限制。可以在文档注释的描述部分或任何标记（例如 @deprecated、@return 或 @param）的文本部分中使用该标记。

例如，下面是一个引用 getComponentAt(int, int) 方法的注释：

使用 {@link #getComponentAt(int, int) getComponentAt} 方法。

根据它，标准 doclet 将生成如下 HTML（假定它引用相同包中另一个类）：

使用 <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> 方法。

它在 web 页上显示为：

使用 getComponentAt 方法。

@param parameter-name description
给“参数”部分添加参数。描述可继续到下一行。

@return description
用 description 文本添加“返回”部分。该文本应描述值的返回类型和容许范围。

@see reference
添加“参见”标题，其中有指向 reference 的链接或文本项。文档注释可包含任意数目的 @see 标记，它们都分组在相同标题下。@see 标记具有三种变体；下面的第三种形式是最常用的形式。
@see "string" 注意 - 该形式在 JDK 1.2 没有用。它不打印引用文本。
为 string 添加文本项。不产生链接。string 是通过该 URL 不可用的书籍或其他信息引用。Javadoc 通过查找第一个字符为双引号（"）的情形来区分它与前面的情况。例如：
@see "Java 编程语言"

这将生成如下文本：

参见：
"Java 编程语言"
@see <a href="URL#value">label</a>
添加 URL#value 定义的链接。其中 URL#value 是相对 URL 或绝对 URL。Javadoc 通过查找第一个字符小于符号（<）区分它与其他情况。例如：
@see <a href="spec.html#section">Java 规范</a>

这将生成如下链接：

参见：
Java Spec
@see package.class#member label
添加带可见文本 label 的链接，它指向 Java 语言中指定名字的文档。其中 label 是可选的；如果省略，则名字将作为可见文本出现，而且嵌入在 <code> HTML 标记中。当想要缩写可见文本或不同于名字的可见文本时，可使用 label。

package.class#member 是 Java 语言中的任何有效名字 -- 包名、类名、接口名、构造函数名、方法名或域名 -- 除了用 hash 字符（#）取代成员名前面的点之外。如果该名字位于带文档的类中，则 Javadoc 将自动创建到它的链接。要创建到外部引用类的链接，可使用 -link 选项。使用另两种 @see 形式的任何一种引用不属于引用类的名字的文档。第一个参数将在指定名字中详细介绍。
label 是可选文本，它是链接的可见标签。label 可包含空格。如果省略 label，则将显示 package.class.member，并相对于当前类和包适当缩短。-- 参见如何显示名字。
空格是 package.class#member 和 label 之间的分界符。括号内的空格不表示标签的开始，因此在方法各参数之间可使用空格。
示例 - 在该示例中，Character 类中的 @see 标记引用 String 类中的 equals 方法。该标记包括两个参数：名字“String#equals(Object)”和标签“equals”。.

/**
* @see String#equals(Object) equals
*/

标准 doclet 将产生类似如下的 HTML 文档：

<dl>
<dt>参见：
<dd><a href="../../java/lang/String#equals(java.lang.Object)">equals</a>
</dl>

它在浏览器中看起来像如下内容，其中标签是可见链接文本：

参见：
equals

指定名字 - package.class#member 名可以是全限定的，例如 java.lang.String#toUpperCase()，也可以不是全限定的，例如 String#toUpperCase() 或 #toUpperCase()。如果不是全限定的，则 Javadoc 使用正常 Java 编译器搜索次序查找它，在 @see 的搜索次序中将进一步介绍。名字可以在括号内包含空格，例如在方法参数之间。

当然使用较短的“部分限定”名字的优点是键入更少，并且源代码中的混乱更少。下表显示的不同的名字形式，其中 Class 可以为类或接口，Type 可以为类、接口、数组或基本数据类型，而 method 可以为方法或构造函数。

@see package.class#member 的典型形式
引用当前类的成员
@see #field
@see #method(Type, Type,...)
@see #method(Type argname, Type argname,...)

引用当前包或导入包中的其他类
@see Class#field
@see Class#method(Type, Type,...)
@see Class#method(Type argname, Type argname,...)
@see Class

引用其他包（全限定）
@see package.Class#field
@see package.Class#method(Type, Type,...)
@see package.Class#method(Type argname, Type argname,...)
@see package.Class
@see package

下述说明适用于上表：

第一套形式（没有类和包）将导致 Javadoc 仅搜索当前类层次。它将查找当前类或接口、其父类或超接口、或其包含类或接口的成员（搜索步骤 1-3）。它不会搜索当前包的其余部分或其他包（搜索步骤 4-5）。
如果任何方法或构造函数输入为不带括号的名字，例如 getvalue，且如果没有具有相同名字的域，则 Javadoc 将正确创建到它的链接，但是将显示警告信息，提示添加括号和参数。如果该方法被重载，则 Javadoc 将链接到它搜索到的第一个未指定方法。
对于所有形式，内部类必须指定为 outer.inner，而不是简单的 inner。
如上所述，hash 字符（#）而不是点（.）用于分隔类和成员。这使 Javadoc 可正确解析，因为点还用于分隔类、内部类、包和子包。当 hash 字符（#）是第一个字符时，它是绝对不可少的。但是，在其他情况下，Javadoc 通常不严格，并允许在不产生歧义时使用点号，但是它将显示警告。
@see 的搜索次序 - Javadoc 将处理出现在源文件（.java）、包文件（package.html）或概述文件（overview.html）中的 @see 标记。在后两种文件中，必须完全限定用 @see 提供的名字。在源文件中，可指定全限定或部分限定的名字。

当 Javadoc 在 .java 中遇到不是全限定的 @see 标记时，它按照与 Java 编译器相同的次序搜索指定名字（Javadoc 将不检测名字空间二义性，因为它假定源代码不会有这些错误）搜索次序在 Java 语言规范第六章“名字”中正式定义，由“内部类规范”修改。Javadoc 在所有相关和导入类和包中搜索该名字。特别地，它按如下次序搜索：

当前类或接口
任何包含类和接口，先搜索最近的
任何父类和超接口，先搜索最近的
当前包
任何导入包、类和接口，按导入语句中的次序搜索
Javadoc 继续对它遇到的每个类重复步骤 1-3 进行搜索，直到找到匹配项。这就是说，当它搜索当前类及其包含类 E 之后，它在搜索 E 的包含类之前先搜索 E 的父类。在步骤 4 和 5 中，Javadoc 不按任何指定的次序（该次序取决于特定编译器）搜索包中的类或接口。在步骤 5 中，Javadoc 将在 in java.lang 中查找，因为它是由所有程序自动导入的。

Javadoc 没有必要在子类中查找，也没有必要在其他包中查找，即使它们的文档在同一次运行中生成。例如，如果 @see 标记位于 java.awt.event.KeyEvent 类中并引用 java.awt 包中的名字，则 javadoc 将不查找该包，除非该类导入它。

如果显示名字 - 如果省略 label，则将显示 package.class.member。一般地，将相对于当前类和包适当缩短它。这里“缩短”是指仅显示必要的名字，使之尽可能短。例如：

方法包含 @see Tag @see 标记显示为
String.toUpperCase() @see String#toLowerCase()
（引用相同类的成员） toLowerCase()
（省略类名）
String.toUpperCase() @see Character#toLowerCase(char)
（引用其他类的成员） Character.toLowerCase(char)
（包括类名）

@see 示例
右边的注释显示了当 @see 标记位于其他包（例如 java.applet.Applet）中时，如何显示名字。

参见：
@see java.lang.String // String
@see java.lang.String The String class // String 类
@see String // String
@see String#equals(Objetc) // String.equals(Object)
@see String#equals // String.equals(java.lang.Object)
@see java.lang.Object#wait(long) // java.lang.Object.wait(long)
@see Character#MAX_RADIX // Character.MAX_RADIX
@see <a href="spec.html">Java Spec</a> // Java 规范
@see "The Java Programming Language" // "Java 编程语言"

@since since-text
用 since-text 指定的内容给生成文档添加“Since”标题。该文本没有特殊内部结构。该标记表示该改变或功能自 since-text 所指定的软件版本之后就存在了。例如：
@since JDK1.1

@serial field-description
用于缺省可序列化域的文档注释中。
可选的 field-description 增强了文档注释对域的描述能力。该组合描述必须解释该域的意义并列出可接受值。如需要，该描述可有多行。

应该对自 Serializable 类的最初版本之后添加的每个可序列化域添加 @since 标记。

要获得私有类的序列化形式，可使用 -private 选项。因而，要生成所有公共类和私有类的序列化形式，可用 -private 选项运行 javadoc。

有关如何使用这些标记的信息，以及相应示例，参见 Java 对象序列化规范中第 1.6 节“建立类的可序列化域和数据的文档。

@serialField field-name field-type field-description
建立 Serializable 类的 serialPersistentFields 成员的 ObjectStreamField 组件的文档。应该对每个 ObjectStreamField 使用一个 @serialField 标记。

@serialData data-description
data-description 建立数据（尤其是 writeObject 方法所写入的可选数据和 Externalizable.writeExternal 方法写入的全部数据）序列和类型的文档，。
@serialData 标记可用于 writeObject、readObject、writeExternal 和 readExternal 方法的文档注释中。

@throws class-name description
@throws 和 @exception 标记同义。用 class-name 和 description 文本给生成的文档添加“抛出”子标题。其中 class-name 是该方法可抛出的异常名。如果该类不是全限定的，则 Javadoc 使用搜索次序查找该类。

@version version-text
当使用 -version 选项时用 version-text 指定的内容给生成文档添加“版本”子标题。该文本没有特殊内部结构。文档注释最多只能包含一个 @version 标记。版本通常是指包含该类或成员的软件（例如 JDK）版本。

可使用标记的地方
下面介绍了在哪些地方可使用标记。注意这四个标记可用于所有文档注释中：@see、@link、@since、@deprecated。

概述文档标记
概述标记可出现在概述页的文档注释中（该文档通常位于叫作 overview.html 的源文件中）。像在任何其他文档注释中一样，这些标记必须位于描述后面。

注意 - {@link} 标记在 JDK 1.2 的概述文档中有一个 bug -- 文档正确显示，但没有链接。

概述标记
@see
{@link}
@since

包文档标记
包标记可出现在包的文档注释中（该文档位于叫作 package.html 的源文件中）。

包标记
@see
{@link}
@since
@deprecated

类和接口文档标记
下面是可出现在类或接口的文档注释中的标记。

类/接口标记
@see
{@link}
@since
@deprecated
@author
@version

类注释示例：
/**
* 代表屏幕上窗口的类。
* 例如：
* <pre>
* Window win = new Window(parent);
* win.show();
* </pre>
*
* @author Sami Shaio
* @version 1.6, 06/25/99
* @see java.awt.BaseWindow
* @see java.awt.Button
*/
class Window extends BaseWindow {
...
}

域文档标记
下面是可出现在域文档注释中的标记。

域标记
@see
{@link}
@since
@deprecated
@serial
@serialField

域注释示例：
/**
* 组件的 X 坐标。
*
* @see #getLocation()
*/
int x = 1263732;

构造函数和方法文档标记
下面是可出现在构造函数或方法的文档注释中的标记。

方法/构造函数标记
@see
{@link}
@since
@deprecated
@param
@return
@throws (@exception)
@serialData

方法文档注释示例：
/**
* 返回指定索引处的字符。索引
* 范围为 <code>0</code> 至 <code>length() - 1</code>.
*
* @param index 想要的字符的索引。
* @return 想要的字符。
* @exception StringIndexOutOfRangeException
* 如果索引不在范围 <code>0</code>
* 到 <code>length()-1</code> 中。
* @see java.lang.Character#charvalue()
*/
public char charAt(int index) {
...
}

命令行参数文件
为了缩短或简化 javadoc 命令，可指定一个或多个其中每行包含一个源文件名或包名的文件。在命令行中，采用 '@' 字符加上文件名的方法将它指定为文件列表。当 javadoc 遇到用字符‘@’开头的参数时，它将操作该文件中的名字，仿佛这些名字位于命令行上一样。

例如，可以在名为 packages 的文件中列出所有包名。该文件可能形如：

com.mypackage1
com.mypackage2
com.mypackage3

然后可用如下命令运行 javadoc：

C:> javadoc -d apidocs @packages

选项
javadoc 工具使用 doclets 确定其输出。除非使用 -doclet 选项指定自定义 doclet ，否则 Javadoc 使用缺省的标准 doclet。Javadoc 提供一套命令行选项，可用于任何 doclet -- 这些选项将在下面的子标题 Javadoc 选项中介绍。标准 doclet 提供了一套额外的命令行选项，它们将在下面的子标题标准 Doclet 提供的选项中介绍。所有选项名都不区分大小写，但是其参数可能区分大小写。

选项包括：

-1.1
-author
-bootclasspath
-bottom
-classpath
-d
-docencoding
-doclet
-docletpath
-doctitle
-encoding
-extdirs
-footer
-group
-header
-help
-helpfile
-J
-link
-linkoffline
-locale
-nodeprecated
-nodeprecatedlist
-nohelp
-noindex
-nonavbar
-notree
-overview
-package
-private
-protected
-public
-sourcepath
-splitindex
-stylesheetfile
-title
-use
-verbose
-version
-windowtitle

Javadoc 选项
-overview i>path\filename
指定 javadoc 应该从 path\filename 所指定的“源”文件中获取概述文档，并将它放到概述页中（overview-summary.html）。其中 path\filename 是相对于 -sourcepath 的相对路径名。
尽管可对 filename 使用任何名字并将它放在 path 指定的任何地方，但是通常将它命令为 overview.html 并将它放入包含最顶级包目录的源目录树中。在该位置，建立包文档时不需要 path，因为 -sourcepath 将指向该文件。例如，如果 java.lang 包的源目录树是 /src/classes/java/lang/，则可以概述文件放到 /src/classes/overview.html。参见实际示例。

有关 path\filename 指定文件的信息，参见概述注释文件。

在一定情况下，将不产生概述页。有关详细信息，参见 HTML 框架。

-public
只显示公有类及成员。

-protected
只显示受保护的和公有的类及成员。这是缺省状态。

-package
只显示包、受保护的和公有的类及成员。

-private
显示所有类和成员。

-help
显示联机帮助，它将列出这些 javadoc 和 doclet 命令行选项。

-doclet class
指定启动用于生成文档的 doclet 的类文件。该 doclet 定义了输出的内容和格式。如果未使用 -doclet 选项，则 javadoc 使用标准 doclet 生成缺省 HTML 格式。该类必须包含 start(Root) 方法。该启动类的路径由 -docletpath 选项定义。

-docletpath classpathlist
指定 doclet 类文件的路径，该类文件用 -doclet 选项指定。如果 doclet 已位于搜索路径中，则没有必要使用该选项。

-1.1
生成具有用 Javadoc 1.1 生成的文档的外观和功能的文档。也就是说，页的背景为灰色，用图像做页眉，使用 bullet 列表而不是表格，具有单级目的目录结构，不包含继承 API，不使用 HTML 框架，并且不支持内部类。该选项还将索引分割成每个字母一个文件。如果想要这种外观，则该选项比 javadoc 1.1 优越之处在于修正了一些错误。
不是所有选项都能用于 -1.1 选项。为了查看哪些选项可用，可执行：

C:> javadoc -1.1 -help

在该列表中显示的 -footer 选项在功能上与本页中其他地方介绍的 -bottom 选项相同。而 -title 选项在功能上与 -doctitle 相同。

-sourcepath sourcepathlist
当将包名传递到 javadoc 命令中时，指定查找源文件（.java）的搜索路径。注意只有当用 javadoc 命令指定包名时才能使用 sourcepath 选项 -- 它将不会定位传递到 javadoc 命令中的 .java 文件。如果省略 -sourcepath，则 javadoc 使用类路径查找源文件（参见 -classpath）。
将 sourcepathlist 设置成正在生成其文档的包的源树的根目录。例如，假定想要为叫作 com.mypackage 的包建立文档，其源文件位于：

C:\user\src\com\mypackage\*.java

在这种情况下，将把 sourcepath 指定为 C:\user\src，该目录包含 com\mypackage，然后提供包名 com.mypackage：

javadoc -sourcepath C:\user\src com.mypackage

这是相当容易记忆的，注意如果将源路径和包名级联到一起，并将点号改为斜杠“/”，则最后将得到该包的完整路径：C:\user\src\com\mypackage.

-classpath classpathlist
指定 javadoc 将在其中查找引用类的路径 -- 引用类是指带文档的类加上它们引用的任何类。Javadoc 将搜索指定路径的所有子目录。classpathlist 可以包含多个路径，它们用分号分隔。有关如何指定 classpathlist，请遵循类路径文档中的指令。
如果省略 -sourcepath，则 Javadoc 使用 -classpath 查找源文件和类文件（为了向后兼容性）。因而，如果想要在不同的路径中搜索源文件和类文件，则应使用 -sourcepath 和 -classpath 两个选项。

例如，如果想要建立 com.mypackage 的文档，其类位于目录 C:\user\src\com\mypackage 中，并且该包依赖于 C:\user\lib 中的库，则将会指定：

C:> javadoc -classpath \user\lib -sourcepath \user\src com.mypackage

与其他工具一样，如果不指定 -classpath，则 Javadoc 将使用 CLASSPATH 环境变量（如果它已设置）。如果二者都未设置，则 Javadoc 将从当前目录中搜索类。

有关 Javadoc 如何使用 -classpath 查找用户类及相关扩展类和自举类的深入介绍，参见如何查找类。

-bootclasspath classpathlist
指定自举类所在路径。它们名义上是 Java 平台类。这个 bootclasspath 是 Javadoc 将用来查找源文件和类文件的搜索路径的一部分。有关详细信息，参见如何查找类。在 classpathlist 中用分号（;）分隔目录。

-extdirs dirlist
指定扩展类所在的目录。它们是任何使用 Java 扩展机制的类。这个 extdirs 是 Javadoc 将用来查找源文件和在文件的搜索路径的一部分。有关详细信息，参见上面的 -classpath。在 dirlist 中用分号（;）分隔目录。

-verbose
在 javadoc 运行时提供更详细的信息。不使用 verbose 选项时，将显示加载源文件、生成文档（每个源文件一条信息）和排序的信息。verbose 选项导致打印额外的信息，指定解析每个 java 源文件的毫秒数。

-locale language_country_variant
指定 javadoc 在生成文档时使用的环境。该参数为环境名，如 java.util.Locale 文档中所述，例如 en_US（英语，美国）或 en_US_WIN（Windows 变量）。
指定环境将导致 javadoc 为各种信息（导航栏中的字符串、列表和表格的标题、帮助文件内容、stylesheet.css 中的注释，等等）选择使用该环境的资源文件。它还指定按字母次序排序列表的排序次序，以及用于确定第一句结束的语句分隔符。它不决定带文档类的源文件中指定的文档注释文本的环境。

-encoding name
指定源文件编码名，例如 EUCJIS/SJIS。如果未指定该选项，则使用平台缺省转换器。

-Jflag
将 flag 直接传递给运行 javadoc 的运行时系统 java。注意在 J 和 flag 之间不能有空格。例如，如果需要确保系统分配 32 兆内存用于处理生成文档，则应按如下使用该标志：
牋 C:> javadoc -J-Xmx32m -J-Xms32m com.mypackage

标准 Doclet 提供的选项
-d directory
指定 javadoc 保存生成的 HTML 文件的目的目录。("d" 表示 "destination.") 省略该选项将导致把文件保存到当前目录中。其中 directory 可以是绝对路径或相对当前工作目录的相对路径。例如，下列代码将生成 com.mypackage 包的文档并将结果保存在 C:\user\doc\ 目录中：
C:> javadoc -d \user\doc com.mypackage

-use
对每个带文档类和包包括一个“用法”页。该页描述使用给定类或包的任何 API 的包、类、方法、构造函数和域。对于给定类 C，使用类 C 的任何东西将包括 C 的子类、声明为 C 的域、返回 C 的方法以及具有 C 类型参数的方法和构造函数。
例如，下面来看一下出现在 String 的“用法”页上的内容。java.awt.Font 类中的 getName() 方法返回类型 String。因而，getName() 使用 String，从而可在 String 的“用法”页上找到该方法。

注意它只产生使用 API 的文档，而不包括实现。如果方法在其实现中使用 String 但不接受字符串参数也不返回字符串，则将不认为它使用 String。

可通过先转到类或包，然后在导航栏上单击“用法”链接，访问生成的“用法”页。

-version
在生成文档中包括 @version 文本。缺省地将省略该文本。

-author
在生成文档中包括 @author 文本。

-splitindex
将索引文件按字母分割成多个文件，每个字母一个文件，再加上一个包含所有以非字母字符开头的索引项的文件。

-windowtitle title
指定放入 HTML <title> 标记中的标题。它将出现在窗口标题栏中和为该页创建的任何浏览器书签（最喜欢的地方）中。该标题不应该包含任何 HTML 标记，因为浏览器将不能正确解释它们。在 title 中的任何内部引号必须转义。如果省略 -windowtitle，则 Javadoc 对该选项使用 -doctitle 的值。

-doctitle title
指定放置在靠近概述概览文件顶部的标题。该标题将作为一级标题，居中地直接放在导航栏下面。title 可包含 html 标记和空格，但是如果这样，则必须用引号将它括起。在 title 中的任何内部引号必须转义。

-title title
该选项不再存在。它仅存在于 Javadoc 1.2 的 Beta 版中。它已重命名为 -doctitle。重命名该选项是为了更清楚地表示它定义文档标题而不是窗口标题。

-header header
指定放置在每个输出文件顶部的页眉文本。该页眉将放在上部导航栏的右边。header 可包含 HTML 标记和空格，但是如果这样则必须用引号将它括起。在 header 中的任何内部引号必须转义。

-footer footer
指定放置在每个输出文件底部的脚注文本。脚本将放置在下部导航栏的右边。footer 可包含 html 标记和空格，但是如果这样，则必须用引号将它括起。在 footer 中的任何内部引号必须转义。

-bottom text
指定放置在每个输出文件底部的文本。该文本将放置在页底，位于下部导航栏的下面。其中 text 可包含 HTML 标记和空格，但是如果这样，则必须用引号将它括起。在 text 中的任何内部引号必须转义。

-link docURL

创建链接指向已用 javadoc-生成的外部引用类的文档。参数 docURL是想要链接到的 javadoc-生成外部文档的 URL。该位置可以是相对的或绝对的 URL。
也就是说，该选项使得可链接到代码所引用但是当前 javadoc 运行没有产生其文档的类。为保证这些链接指向有效页，必须知道那些 HTML 页所在位置，并用 docURL 指定其位置。例如，这将允许第三方文档链接到 java.sun.com 上的 java.* 文档。另一种用途是用于包集之间的交叉-链接：对一个包集执行 javadoc，然后再对另一个包集运行 javadoc，在两个集合之间创建双向链接。另一个用途是作为到更新文档的“hack”：在整个包集上执行 javadoc，然后对更改过的包的较小集再次运行 javadoc，从而将更新文件插回到原集中。（这样做可节省时间，但是需要小心使用 -- 如果从子集中添加或删除 API，则将会丢失或破坏索引中的链接。）

按如下使用 -link 选项：

省略 -link 选项，使 javadoc 只创建指向当前运行中正在生成的文档中 API 的链接。（不使用 -link 选项，Javadoc 将不创建外部引用文档的链接，因为它不知道该文件是否存在（或其位置）。）
包括 -link 选项，使用 javadoc 还创建指向位于 docURL 的外部引用类文档的链接。
注意如果 URL 位于 WWW 上，则 javadoc 在生成文档时必须具有 web 连接以访问 package-list。如果不能访问，则可使用 -linkoffline 代替。

Package List - -link 选项需要一个名为 package-list 的文件（它由 Javadoc 生成）位于用 -link 指定的 URL 中。package-list 文件是简单的文本文件，列出在该位置有文档的包名。在下面将介绍 Javadoc 如何使用包列表。

例如，Java 平台 1.2 API 的包列表位于 java.sun.com/products/jdk/1.2/docs/api/package-list。并且以如下内容开始：

java.applet
java.awt
java.awt.color
java.awt.datatransfer
java.awt.dnd
java.awt.event
java.awt.font
等等。

当 javadoc 不带 -link 选项运行时，在它生成文档时，当它遇到属于外部引用类的名字时，它将打印不带链接的名字。但是，如使用 -link 选项，则 Javadoc 将在指定 docURL 的 package-list 文件中搜索该包名。如果它查找到该包名，则将 URL 添加到该名字前面。（如果 URL 是相对路径并且 -d 目的目录选项是相对路径，则 Javadoc 将目的目录的相对路径添加到 URL 中，以使链接在目的目录中可用。）

为了不产生无效链接，外部引用的所有文档都必须在指定 URL 存在。Javadoc 将不会检查这些页的存在 -- 它只检查 package-list 的存在。

如果 javadoc 的参数是源文件而不是包，则将创建 package-list, 文件但是为空。

示例 - 例如，下面命令导致 Javadoc 在给定 URL 查找 package-list 文件，读取该文件中的包名，然后在添加指向那些外部包中 API 的链接时使用给定 URL：

C:> javadoc -link java.sun.com/products/jdk/1.2/docs/api com.mypackage

多链接 - 可提供多个 -link 选项，链接到任意多个外部生成文档。已知 Bug - Javadoc 1.2 有一个已知 bug，它使得不能提供多个 -link 命令。在未来版本中将会修正它。

为每个要链接的外部文档指定不同的链接选项：

牋 C:> javadoc -link docURL1 -link docURL2 ... -link docURLn com.mypackage

其中 docURL1、 docURL2、 ... docURLn 分别指向外部文档的根目录，各自包含一个 package-list 文件。

交叉链接 - 注意在交叉链接两个或多个还没有生成的文档时，可能需要“启动”。也就是说，如果任何文档的 package-list 都不存在，则在对第一个文档运行 javadoc 时，第二个文档的包列表文件也将不存在。因而，要创建外部链接，必须在生成第二个文档之后重新生成第一个文档。

在这种情况中，第一次生成文档的目的是创建其包列表（如果能确定包名，也可手工创建包列表）。然后生成带外部链接的第二个文档。Javadoc 在需要的外部 package-list 文件不存在时打印警告信息。

更新文档 - -link 选项的第三个用途是如果项目有数十个或数百个包，并且已对整个目录树运行了 javadoc，现在，在单独的运行中，想要快速地进行一些小的修改，并对源目录树的一小部分重新运行 javadoc，这时它是非常有用的。这有些类似于 hack，因为它只在改变文档注释时才能正常工作，而修改签名则不行。如果想要在源代码中添加、删除或改变任何签名，则可能在索引、包目录树、继承成员列表、用法页或其他位置出现无效链接。

首先，为这次小运行新建一个目的目录，并将 -link 和 -d 设置成相同的相对路径：如果原文档位于目录 html 中，则为：

C:> javadoc -d update -linkoffline . html com.mypackage

当 javadoc 完成后，复制 update 中生成的文件并覆盖 html 中的原文件。

背景知识：一般地，在 javadoc 运行时，它有可能为其生成页中出现的名字产生链接：例如在签名、@see 标记、{@link} 标记、概览、层次、概述和索引中。有些链接将转到当前运行中生成的页，而其他链接有可能转到不是在当前运行中生成的页。

-linkoffline docURL packagelistURL

该选项为外部引用类名字创建指向文档的链接，其中：
docURL 是想要链接到的 javadoc 生成的外部文档的根目录的 URL。该位置可以是相对的或绝对的 URL。
packagelistURL 是包含文档的包列表文件所在目录的 URL。（如果需要，可手工创建该文件。）
该选项是 -link 的一种变体。如果在运行 javadoc 时包列表文件在 docURL 位置不存在，则可使用 -linkoffline。如果知道文档链接到的包名和文档所在位置，则可以在该包列表文件实际存在于该位置之前，生成带外部链接的文档。这使得可用自己的包列表副本，生成具有适当链接的文档。

当需要生成链接指向包名已知但尚未发布的新外部文档（但是还没有建立）时，这时非常有用的。这使得两个公司可同时发布他们的文档。它还允许生成链接到没有包列表文件的外部文档（或许它是用 Javadoc 1.0、1.1 或最高 1.2 Beta3 生成）的文档。

注意该选项在运行 javadoc 时不需要访问文档 URL。因而，即使该 URL 位于 WWW 上，在生成文档时也不需要 web 链接。

如下所示，要使用该选项，请指定 docURL1（javadoc 生成的外部引用类的文档的位置）和 packagelistURL1（其包列表文件的位置）。如果它们具有相同位置，则可仅使用 -link 选项。对每个想要引用的生成文档，需要包括 -linkoffline 一次：

C:> javadoc -linkoffline docURL1 packagelistURL1 -linkoffline docURL2 packagelistURL2

例如，下面的命令使用第一个参数给定的 URL 添加链接，并在第二个参数给定的路径中查找 package-list 文件。

C:> javadoc -linkoffline java.sun.com/products/jdk/1.2/docs/api /usr/web/work/products/jdk/1.2/docs/api/

-group groupheading packagepattern:packagepattern:...
将概述页上的包分成指定的组，每组一个表格。可以用不同的 -group 选项指定每个组。各组按命令行中指定的次序出现在页面上，组内的包按字母排序。对于给定 -group 选项，与 packagepattern 表达式列表匹配的包出现在标题为 groupheading 的表格中。
groupheading 可以为任何文本，并可包括空格。该文本将放置在该组的表格标题中。
packagepattern 可以为任何包名，也可以为任何包名的开头后跟星号（*）。星号是通配符，表示“匹配任何字符”。它是唯一允许的通配符。一组中可包包括多个模式，并用分号（;）分隔它们。
注意：如果在模式或模式列表中使用星号，则模式列表必须位于引号内部，例如 "java.lang*:java.util"

如果没有提供任何 -group 选项，则所有包都将放在一组中，并且其标题为“包”。如果所有组未包括全部带文档包，则剩余的任何包将出现在一个单独的组中，且其标题为“其他包”。

例如，下面的选项将四个带文档包分成“核心包”、“扩展包”和“其他包”。注意后面的“点”号不出现在 "java.lang*" 中 -- 包括点号，例如“java.lang.*”将忽略 java.lang 包。

C:> javadoc -group "核心包" "java.lang*:java.util"
-group "扩展包" "javax.*"
java.lang java.lang.reflect java.util javax.servlet java.new

结果分组为：

核心包
java.lang
java.lang.reflect
java.util
扩展包
javax.servlet
其他包
java.new

-nodeprecated
防止在文档中生成任何不鼓励使用的 API。它执行 -nodeprecatedlist 所做的事情，并且它不在文档其余部分生成任何不鼓励使用的 API。当编写代码并不想被不鼓励使用的代码分心时，这是非常有用的。

-nodeprecatedlist
防止在生成文件中包含不鼓励使用的 API 列表（deprecated-list.html）并防止在导航栏中包含该页的链接。（但是，javadoc 继续在文档其余部分生成不鼓励使用的 API。）如果源代码未包含不鼓励使用的 API，并且想要导航栏更干净，则它是非常有用的。

-notree
在生成文档中忽略类/接口层次。缺省地，将产生该层次。

-noindex
在生成文档中忽略索引。缺省地，将产生索引。

-nohelp
在输出的每页顶部和底部的导航栏中忽略“帮助”链接。

-nonavbar
防止产生导航栏、页眉和脚注，否则它们将出现在生成页的顶部和底部。它对“bottom”选项没有影响。当只对内容感兴趣并且没有必要导航时，例如仅将文件转换成 PostScript 或 PDF 以进行打印，-nonavbar 选项是非常有用的。

-helpfile path\filename
指定顶部和底部导航栏中“帮助”链接所链接到的替代帮助文件 path\filename 的路径。不使用该选项时，Javadoc 自动创建帮助文件 help-doc.html，它在 Javadoc 中硬编码。该选项使得可覆盖这种缺省情况。其中 filename 可以是任何名字，不局限于 help-doc.html -- Javadoc 将相应调整导航栏中的链接。例如：
C:> javadoc -helpfile C:\user\myhelp.html java.awt

-stylesheetfile path\filename
指定替代 HTML 样式表单文件的路径。不使用该选项时，Javadoc 将自动创建样式表单文件 stylesheet.css，它在 Javadoc 中硬编码。该选项使得可覆盖这种缺省情况。其中 filename 可以是任何名字，不局限于 stylesheet.css。例如：
C:> javadoc -stylesheetfile C:\user\mystylesheet.css com.mypackage

-docencoding name
指定输出 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 = 'JavaTM Platform 1.2 Final API Specification'
HEADER = 'Java Platform 1.2 Final'
BOTTOM = '<a href="http://java.sun.com/cgi-bin/bugreport.cgi"> 提交
bug 或功能 </a> Java 是 Sun Microsystems , Inc 在美国和其他国家
的商标或注册商标。 Copyright 1993-1998
Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
保留所有权利。'
GROUPCORE = '"核心包" "java.*:com.sun.java.*:org.omg.*"
GROUPEXT = '"扩展包" "javax.*"'

如果省略 -windowtitle 选项，则 javadoc 将文档标题复制到窗口标题。-windowtitle 选项是没有必要的，除非文档标题包含 HTML 标记。

如果像这里所做的一样省略 -footer 选项，则 javadoc 将页眉文本复制到脚注文本。

其他重要的选项是 -classpath 和 -link。

环境

CLASSPATH
提供 javadoc 用于查找用户类文件路径的环境变量。该环境变量将被 -classpath 选项覆盖。用分号分隔目录，例如：

.;C:\classes;C:\home\java\classes; 0

http://fuguotao.5d.cn/

评论Comments