`
lhx1026
  • 浏览: 307072 次
  • 性别: Icon_minigender_2
  • 来自: 广州
社区版块
存档分类
最新评论

javadoc - Java API 文档生成器

    博客分类:
  • java
阅读更多

javadoc - Java API 文档生成器

从 Java 源文件生成 API 文档 HTML 页。


目录


<!-- ==================== SYNOPSIS ======================= -->

结构

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
以任何次序包含包名和源文件的一个或多个文件。


<!-- =================== DESCRIPTION ======================= -->

说明

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 的类路径中。

<!-- ====================== DOCLETS ========================= -->

Javadoc Doclets

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

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

相关文档

<!-- ====================== TERMINOLOGY ========================= -->

术语

在 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 选项链接外部引用类。


<!-- ====================== SOURCE FILES ========================= -->

源文件

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">
     */


<!-- ====================== GENERATED FILES ========================= -->

生成的文件

缺省地,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 接口用法页
<!-- ================= DOCUMENTATION COMMENTS ==================== -->

文档注释

注释源代码

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

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

下面是文档注释:

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

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

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

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

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

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

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


<!-- ====================== TAGS ========================= -->

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 的内嵌链接。该标记中 namelabel 的语法与 @see 标记完全相同,如下所述,但是它产生内嵌链接而不是在“参见”部分中放置链接。该标记用花括号开始并用花括号结束,以使它区别于其他内嵌文本。如果在标签内需要使用“}”,则请使用 HTML 实体表示法 &#125;

对于一个语句中所允许的 {@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 # memberlabel 之间的分界符。括号内的空格不表示标签的开始,因此在方法各参数之间可使用空格。

示例 - 在该示例中,Character 类中的 @see 标记引用 String 类中的 equals 方法。该标记包括两个参数: 名字“String#equals(Object) ”和标签“equals ”。.

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

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

<dl>
<dt><b>参见:</b>
<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 在所有相关和导入类和包中搜索该名字。特别地,它按如下次序搜索:

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

Javadoc 继续对它遇到的每个类重复步骤 1-3 进行搜索,直到找到匹配项。这就是说,当它搜索当前类及其包含类 E 之后,它在搜索 E 的包含类之前先搜索 E 的父类。<!-- The order of steps 2 and 3 above don't matter. A compiler error occurs if a member is both in an enclosing class and a superclass, according to Atul. --> 在步骤 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
                          <!--  [1] -->
@see java.lang.String The String class  //   String 类
                <!--  [2] -->
@see String                             //  String
                          <!--  [3] -->
@see String#equals(Objetc)              //  String.equals(Object)
           <!--  [4] -->
@see String#equals                      //  String.equals(java.lang.Object)
 <!--  [5] -->
@see java.lang.Object#wait(long)        //  java.lang.Object.wait(long)
     <!--  [6] -->
@see Character#MAX_RADIX                //  Character.MAX_RADIX
             <!--  [7] -->
@see <a href="spec.html">Java Spec</a>  //  Java 规范
           <!--  [8] -->
@see "The Java Programming Language"    //  "Java 编程语言"        <!--  [9] -->

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

@serial field-description
用于缺省可序列化域的文档注释中。

可选的 field-description 增强了文档注释对域的描述能力。该组合描述必须解释该域的意义并列出可接受值。如需要,该描述可有多行。

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

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

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

<!-- For FCS, we will add a link in the manpage that will point to the Serialization Enhancements page, where we will add a section called "Guidelines for Using Serialization" or something to that effect. We have a file on our internal website that contains most of the information, including how to deal with the warnings, but it is written for an internal audience. We will clean it up and add it to the new topic for FCS. -jendrock -->

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

@serialData data-description
data-description 建立数据(尤其是 writeObject 方法所写入的可选数据和 Externalizable.writeExternal 方法写入的全部数据)序列和类型的文档,。

@serialData 标记可用于 writeObjectreadObjectwriteExternalreadExternal 方法的文档注释中。

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

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


<!-- ==================== WHERE TAGS CAN BE USED ===================== -->

可使用标记的地方

下面介绍了在哪些地方可使用标记。注意这四个标记可用于所有文档注释中:@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) {
       ...
    }


<!-- ============== COMMAND LINE ARGUMENT FILE ======================= -->

命令行参数文件

为了缩短或简化 javadoc 命令,可指定一个或多个其中每行包含一个源文件名或包名的文件。在命令行中,采用 '@ ' 字

分享到:
评论

相关推荐

    maven-javadoc-plugin 中文 注释 API 解决乱码 pom xml

    在软件开发过程中,API文档对于提高代码可读性、方便团队成员之间的交流至关重要。Maven作为一款强大的自动化构建工具,在项目构建、依赖管理等方面发挥着重要作用。其中,`maven-javadoc-plugin`插件能够自动生成...

    javadoc-12.1-tc-api.rar西门子teamcenter二次开发java api接口

    `javadoc-12.1-tc-api.rar` 是一个包含Teamcenter 12.1版本的Java API文档的压缩文件,Javadoc是一种标准工具,用于从Java源代码中生成API文档,为开发人员提供清晰的接口说明和使用指南。通过这个文档,开发者可以...

    Java API文档.docx

    `javadoc`是Java开发工具包(JDK)自带的文档生成器,它可以从源代码中提取注释并生成API文档。通过在命令行中指定源代码路径和选项,开发者可以自定义要生成的文档内容。生成的HTML文件通常包括类图、继承关系图以及...

    Spring4.1.5-javadoc-api.rar

    Javadoc是一种由Java提供的用于生成API文档的工具,它可以将注释转化为专业格式的文档,方便开发者理解和使用。通过Javadoc,我们可以快速查找类、接口、方法等的定义,以及它们的参数、返回值、异常信息和示例代码...

    本科毕业论文---javascript在线api文档生成文献综述.doc

    现有的API文档生成技术,如Java的javadoc,JavaScript的Jsdoc Toolkit等,通过在代码中添加特定标记来辅助生成文档,但这种方式增加了开发者的工作负担。 在API文档生成过程中,编译原理起着重要作用。词法分析和...

    activiti-javadoc-full-5-16

    Java文档(Javadoc)是Java开发中的一个重要工具,它用于生成关于源代码的API文档,帮助开发者理解和使用库、框架或服务提供的接口和类。在这一版本的Javadoc中,开发者可以找到关于Activiti API的所有详细信息,...

    zk-javadoc-5.0.5

    Javadoc是一种特殊格式的注释,用于生成关于Java类库的API文档,包括类、接口、方法、构造函数等的详细信息。通过Javadoc,开发者可以了解每个类的功能、使用方法以及参数说明,从而更有效地编写代码。 标签“zk-...

    k8s的Java客户端的帮助文档,从官网代码生成的JavaDoc

    这个JavaDoc文档集合是针对Kubernetes Java客户端的详细API参考,由官方代码自动生成,适用于版本12.0.0,它对应的是Kubernetes 1.20版本。以下将详细介绍该Java客户端的关键知识点。 1. **客户端初始化**: 在...

    JDK10-Java Platform, Standard Edition ,Javadoc Guide-26.pdf

    Javadoc是Java平台标准版提供的一个文档生成工具,用于生成Java应用程序的API文档。Javadoc可以根据Java源代码生成相应的文档,包括类、方法、字段等信息。Javadoc还提供了许多标签和参数,用于自定义文档的生成方式...

    java 自己的doc文件生成 api说明文档工具2017

    Java API文档生成工具是开发过程中不可或缺的一部分,它帮助开发者理解并使用库、框架或系统提供的功能。`javadoc`是Java官方提供的一种工具,用于从源代码中的注释生成HTML格式的API文档,使得开发者可以方便地查阅...

    activiti-5.16 api离线文档+用户手册

    Javadoc 是Java编程语言中的一个标准工具,用于从源代码中自动生成文档,它详细描述了类、接口、方法和字段。在 `activiti-javadoc-5.16` 中,你可以找到关于Activiti 5.16的所有公共API的详细说明。这些文档包含了...

    POI包及API

    在标题提到的"POI包及API"中,包含了多个版本为3.11的POI库的jar文件以及一个名为"poiapi.zip"的API文档,这些资源对于Java开发者来说非常有用,尤其是需要处理Excel数据的时候。 1. **POI组件**: - **poi-ooxml-...

    Java帮助文档 JDK全系列 官方中英下载地址.docx

    - **javadoc**:文档生成器,通过解析源代码中的注释,自动生成API文档,便于其他开发者理解和使用代码。 - **jdb**:Java调试器,帮助开发者定位和修复程序中的错误。 2. JDK还包括Java运行环境(JRE): - JRE...

    生成Javadoc文档

    - **-doclet**:指定使用的doclet类,允许自定义文档生成器。 - **-docletpath**:指定doclet类路径。 - **-author**:包含作者信息。 - **-version**:包含版本信息。 - **-use**:包含“使用”标签,展示某个类或...

    java-api帮助文档

    以上只是JDK 1.9 API的一些关键改进和新增功能,实际的API文档涵盖了更广泛的内容,包括类库的每一个细节、方法的使用示例以及异常处理等。通过深入学习和理解这些API,开发者能够更好地利用Java 1.9的特性,编写出...

    Java JDK10.1中英双语API文档

    2. **JDK (Java Development Kit)**: JDK是Java开发的基础,包含了Java编译器(javac)、Java运行时环境(JRE)以及各种开发工具,如Javadoc(生成API文档的工具)、JAR(打包工具)和JDB(调试器)等。 3. **API ...

    Spring-framework-4.3

    本文将深入探讨Spring框架4.3版本,结合其提供的Javadoc-API文档,帮助开发者更好地理解和利用这一强大的框架。 一、Spring框架概述 Spring是一个开源的Java平台,主要目标是简化Java企业级应用的开发。它通过依赖...

    java开发文档API

    JDK是Java的基础,它包含了Java运行时环境(JRE)、编译器(javac)、Javadoc工具(用于生成API文档)以及一系列的实用工具,如jar打包工具、jconsole性能监视器等。JDK的版本更新频繁,每次更新都会带来新的特性和...

    sun-java6-jdk

    1. **Java Development Kit (JDK)**:JDK是Java程序员开发Java应用程序的基础,包括了Java编译器(javac)、Java虚拟机(JVM)、Java应用程序启动器(java命令)、Java文档生成器(javadoc)以及一系列用于调试、...

    javascript在线api文档生成文献-综述设计论文.doc

    现有的API文档生成工具,如Java的javadoc和JavaScript的Jsdoc Toolkit,通过注解方式帮助生成文档。然而,这种方法增加了编写负担。API文档生成涉及到编译原理,包括词法分析和语法分析。词法分析器将源代码分解成...

Global site tag (gtag.js) - Google Analytics