标记格式化多行的缩进时，例如样本代码所示。没有前导星号，生成文档中的缩进将丢失，因为前导空格被删除。） 



每个文档注释的首句应该为概览名，包含所声明实体的完整简要描述。该语句在第一个句号处结束后跟空格、制表或行结束符，或在第一个 标记 处结束。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 通过查找第一个字符小于符号（ 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>pathfilename 

指定 javadoc 应该从 pathfilename 所指定的“源”文件中获取概述文档，并将它放到概述页中（overview-summary.html）。其中 pathfilename 是相对于 -sourcepath 的相对路径名。

尽管可对 filename 使用任何名字并将它放在 path 指定的任何地方，但是通常将它命令为 overview.html 并将它放入包含最顶级包目录的源目录树中。在该位置，建立包文档时不需要 path，因为 -sourcepath 将指向该文件。例如，如果 java.lang 包的源目录树是 /src/classes/java/lang/，则可以概述文件放到 /src/classes/overview.html。参见 实际示例。



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



在一定情况下，将不产生概述页。有关详细信息，参见 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:usersrccommypackage*.java



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



javadoc -sourcepath C:usersrc com.mypackage



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





-classpath classpathlist 

指定 javadoc 将在其中查找 引用类 的路径 -- 引用类是指带文档的类加上它们引用的任何类。Javadoc 将搜索指定路径的所有子目录。classpathlist 可以包含多个路径，它们用分号分隔。有关如何指定 classpathlist，请遵循 类路径 文档中的指令。

如果省略 -sourcepath，则 Javadoc 使用 -classpath 查找源文件和类文件（为了向后兼容性）。因而，如果想要在不同的路径中搜索源文件和类文件，则应使用 -sourcepath 和 -classpath 两个选项。



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



  C:> javadoc -classpath userlib -sourcepath usersrc 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:userdoc 目录中： 

  C:> javadoc -d userdoc 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  标记中的标题。它将出现在窗口标题栏中和为该页创建的任何浏览器书签（最喜欢的地方）中。该标题不应该包含任何 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 指定其位置。例如，这将允许第三方文档链接到 http://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 的包列表位于 http://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 http://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 http://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 pathfilename 

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

  C:> javadoc -helpfile C:usermyhelp.html java.awt



 



-stylesheetfile pathfilename 

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

  C:> javadoc -stylesheetfile C:usermystylesheet.css com.mypackage



 



-docencoding name 

指定输出 HTML 文件的编码方式。 







简单示例

可以对整个包或单个类运行 javadoc。每个包名有一个相应的目录名。在下面的示例中，源文件位于 C:homesrcjavaawt*java。目的目录是 C:homehtml。 



建立包的文档

要建立包的文档，该包的源文件（*.java）必须位于一个与该包名字相同的目录中。如果包名由几个标识符组成（用点号分隔），则每个标识符代表一个不同的目录。因而，所有 java.awt 类必须位于名为 javaawt 的目录中。可用如下两种方式之一运行 javadoc -- 通过改变目录（用 cd）或使用 sourcepath 选项。不能使用通配符指定多个包。



情况 1- 换到包目录 - 换到全限定包的父目录。然后运行 run javadoc，并提供想要建立其文档的一个或多个包的名字：

  C:> cd C:homesrc  C:> javadoc -d C:homehtml java.awt java.awt.event



情况 2 - 从任何目录 - 在这种情况下，当前目录是什么没有关系。运行 javadoc 时用 sourcepath 提供全限定包的父目录，并提供想要建立其文档的一个或多个包的名字：

  C:> javadoc -d C:homehtml -sourcepath C:homesrc java.awt java.awt.event



这两种情况都将产生包 java.awt 和 java.awt.event 中公共和保护类和接口的 HTML 格式文档，并将 HTML 文件保存在指定目的目录（C:homehtml）中。因为要生成两个或多个包，所以文档具有三个框架 -- 包列表、类列表和主页。 



建立类的文档

要建立一个或多个源文件（.java）的文档，这些文件不必位于特定目录中。可以用如下两种方式之一运行 javadoc -- 通过改变目录（用 cd）或完全指定 .java 文件的路径。选项 -sourcepath 在建立源文件的文档时没有作用。可使用命令行通配符，例如星号（*），指定多个类。



情况 1 - 换到源目录 - 换到保存 .java 文件的目录。然后运行 javadoc，并提供想要建立其文档的一个或多个源文件名。

  C:> cd C:homesrcjavaawt

  C:> javadoc -d C:homehtml 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:homehtml C:homesrcjavaawtButton.java C:homesrcjavaawtGraphics*.java



该示例产生类 Button 和以 Graphics 开头的类的 HTML 格式文档。





建立包和类的文档

可同时建立整个包和单个类的文档。下面是一个混合前两个示例的示例。可使用 -sourcepath 指定包的路径但不作为单个类的路径。



  C:> javadoc -d C:homehtml -sourcepath C:homesrc java.awt C:homesrcjavaappletApplet.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 = ' 提交

    bug 或功能 

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:homejavaclasses 







另请参阅

javac 

java 

jdb 

javah 

javap 

Javadoc 主页 

如何为 Javadoc 编写文档注释 

如有意见，请发送到： javadoc-tool@sun.com

您可能感兴趣的文章: