javadoc - Java API 文档生成器详解 转贴

目录

• 结构
• 说明
  • 相关文档
  • Javadoc Doclets
  • 术语
• 源文件
• 生成的文件
• 文档注释
  • 注释源代码
• Javadoc 标记
• 使用标记的地方
• 命令行参数文件
• 选项
  • Javadoc 选项
  • 标准 Doclet 提供的选项
• 简单示例
  • 建立包的文档
  • 建立类的文档
  • 建立包和类的文档
• 实际示例
• 环境
  • CLASSPATH
• 参阅

---

结构

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

可对 整个包、单个源文件 或 二者 运行 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 选项链接外部引用类。 解析 Java 源文件中的声明和文档注释，并产生相应的 HTML 页（缺省），描述公有类、保护类、内部类、接口、构造函数、方法和域。

源文件

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

包注释文件

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

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

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

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

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

概述注释文件

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

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

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

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

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

其他未处理文件

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

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

    /**     * 该按钮类似如下：     *      */

生成的文件

缺省地，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-.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 解析文档注释时，将去掉每行中的前导星号（*）；初始星号（*）字符前面的空格和制表字符也丢弃。如果省略一行上的前导星号，则所有前导空格将被去除。（在某种程度上，可以忽略前导星号。由于省略前导星号导致问题的一种情况是用

 标记格式化多行的缩进时，例如样本代码所示。没有前导星号，生成文档中的缩进将丢失，因为前导空格被删除。） 
 
   
每个文档注释的首句应该为概览名，包含所声明实体的完整简要描述。该语句在第一个句号处结束后跟空格、制表或行结束符，或在第一个 标记 处结束。Javadoc 将首句复制到 HTML 页顶部的成员概览中。
 
   
文档注释只有在位于类、接口、构造函数、方法或域声明前面才能被识别。每个声明只有一个文档注释为 Javadoc 工具所识别。
 
   
当在文档注释中嵌入 HTML 标记时，不应使用 HTML 标题标记例如 
 和 
，因为 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（假定它引用相同包中另一个类）：

使用 getComponentAt 方法。

它在 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 label

添加 URL#value 定义的链接。其中 URL#value 是相对 URL 或绝对 URL。Javadoc 通过查找第一个字符小于符号（ <）区分它与其他情况。例如：

     @see Java 规范

这将生成如下链接：

参见：

Java Spec

@see package.class # member label

添加带可见文本 label 的链接，它指向 Java 语言中指定名字的文档。其中 label 是可选的；如果省略，则名字将作为可见文本出现，而且嵌入在 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 文档：

参见：
equals

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

参见：

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 在所有相关和导入类和包中搜索该名字。特别地，它按如下次序搜索：

1. 当前类或接口
2. 任何包含类和接口，先搜索最近的
3. 任何父类和超接口，先搜索最近的
4. 当前包
5. 任何导入包、类和接口，按导入语句中的次序搜索

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 Java Spec  //  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

类注释示例：

/** * 代表屏幕上窗口的类。 * 例如： * 
 *    Window win = new Window(parent); *    win.show(); * 
 * * @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

方法文档注释示例：

    /**     * 返回指定索引处的字符。索引     * 范围为 0 至 length() - 1.     *     * @param     index  想要的字符的索引。     * @return    想要的字符。     * @exception StringIndexOutOfRangeException     *              如果索引不在范围 0     *              到 length()-1 中。     * @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。如果未指定该选项，则使用平台缺省转换器。

-J flag 将 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