📄 javadoc- java api 文档生成器.htm
字号:
<DT><I>引用类</I>
<DD>在带文档的类和接口的定义（实现）中显式引用的类和接口。引用的例子包括返回类型、参数类型、强制转换类型、已实现接口、导入类，等等。在文档注释（例如
@see 标记）中引用的类不算作引用类。当 Javadoc 运行时，它将 javadoc
引导类路径和类路径中所有的引用类加载到内存中。（对于没有找到的引用类，Javadoc 将显示“类未找到”警告信息。） Javadoc
可从类文件中获得足够的信息，以确定其存在性及其成员的全限定名字。
<P><A name=externalreferencedclasses></A></P>
<DT><I>外部引用类</I>
<DD>在 javadoc 运行期间没有生成其文档的引用类。也就是说，这些类对于该次 javadoc
运行是外部的。文档中名字到这些类的链接称为<I>外部引用</I>或<I>外部链接</I>。例如，如果仅对 <CODE>java.awt</CODE>
包运行 javadoc，则 <CODE>java.lang</CODE> 中的任何类（如 Object）都是外部引用类。可使用
<CODE>-link</CODE> 选项链接外部引用类。 </DD></DL></BLOCKQUOTE>
<P><BR><!-- ====================== SOURCE FILES ========================= --><A
name=sourcefiles></A></P>
<H2>源文件</H2>
<BLOCKQUOTE>
<P>Javadoc 将根据四种不同的“源”文件生成输出： Java
语言源文件（.java）、包注释文件、概述注释文件和其他未处理文件。下面介绍了后三种类型。</P>
<P><A name=packagecomment></A></P>
<H3>包注释文件</H3>
<P>每个包具有它自己的文档注释，保存在其自己的“源”文件中，Javadoc
将把它合并到生成的包概览页中。通常可在这个注释中包括适用于整个包的任何文档。</P>
<P>要创建包注释文件，必须将它命名为 <B><CODE>package.html</CODE></B> 并将它与 <CODE>.java</CODE>
文件一起放在源树中的包目录中。Javadoc 将自动在该位置查找该文件名。注意该文件名对于所有包都是相同的。</P>
<P>包注释文件的内容是一个大文档注释，用 HTML 编写，像所有其他注释一样，但有一个例外： 文档注释不应该包括注释分隔符
<CODE>/**</CODE> 和 <CODE>*/</CODE> 或前导星号。在编写注释时，第一句应该是关于包的概览，并且在
<CODE><body></CODE> 和第一句之间不应该插入任何标题或其他文本。可包括 <A
href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#packagetags">package
标记</A>；与所有文档注释一样，除了 <CODE>{@link}</CODE> 之外的所有标记都应该位于描述之后。如果添加
<CODE>@see</CODE> 标记，则它必须是全限定名字。</P>
<P>当 Javadoc 运行时，它将自动查找该文件；如果找到，则 Javadoc 做下列事情：
<UL>
<LI>复制 <CODE><body></CODE> 和 <CODE></body></CODE>
标记之间的全部内容以进行处理。
<LI>处理存在的任何<A
href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#packagetags">包标记</A>。
<LI>在它生成的包概览页底部插入处理后的文本，例如 <A
href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/api/java/applet/package-summary.html">包概览</A>。
<LI>将包注释的第一句复制到包概览页和概述页（例如<A
href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/api/overview-summary.html">概述概览</A>）的顶部。确定语句结尾用的规则和确定类和成员描述第一个语句用的规则相同。
</LI></UL>
<P><A name=overviewcomment></A></P>
<H3>概述注释文件</H3>
<P>每个要为之建立文档的应用程序或包集可以有它自己的概述文档注释，保存在其自己的“源”文件中，Javadoc
将把它合并到生成的概述页中。在该注释中通常可包括适用于整个应用程序或包集的任何文档。</P>
<P>要创建概述注释文件，可将该文件命名为想要的任何名字（通常为
<B><CODE>overview.html</CODE></B>）并将它放置在任何地方（通常位于源树的最顶层中）。注意对于相同源文件集可有多个概述注释文件，以用于对不同包集多次运行
javadoc。例如，如果 <CODE>java.applet</CODE> 包的源文件包含在
<CODE>/home/user/src/java/applet</CODE> 目录中，则可创建概述注释文件
<CODE>/home/user/src/overview.html</CODE>。</P>
<P>概述注释文件的内容是一个大文档注释，用 HTML
编写，与前面介绍的包注释文件类似。有关详细内容，参见描述。在编写注释时，要重做，第一句应该是关于应用程序或包集的概览，并且在
<CODE><body></CODE> 和第一句之间不要插入标题或任何其他文本。可包括 <A
href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#overviewtags">概述标记</A>；与所有文档注释一样，除了
<CODE>{@link}</CODE> 之外的所有标记都就位于描述之后。如果添加 <CODE>@see</CODE> 标记，则它必须是全限定名字。</P>
<P>当运行 Javadoc 时，可用 <A
href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#overview">-overview</A>
选项指定概述注释文件。然后将以与包注释文件类似的方法处理该文件。
<UL>
<LI>复制 <CODE><body></CODE> 和 <CODE></body></CODE>
标记之间的全部内容以进行处理。
<LI>处理存在任何 <A
href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#overviewtags">概述标记</A>。
<LI>将处理过后的文本插入到生成的概述页（例如 <A
href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/api/overview-summary.html">概述概览</A>）的底部。
<LI>将概述注释的第一句复制到概述概览页的顶部。 </LI></UL>
<P><A name=unprocessed></A></P>
<H3>其他未处理文件</H3>
<P>还可在源文件中包括想要 Javadoc 复制到目的目录中的任何其他文件。这通常包括图形文件、示例 Java
源文件（.java）和类文件（.class）以及其内容远超过常规 Java 源文件文档注释的独立 HTML 文件。</P>
<P>要包括未处理文件，请将它们放入一个叫作 <B><CODE>doc-files</CODE></B>
的目录中，它可以是任何包目录的子目录。每个包可以有一个这种子目录。例如，如果想要在 <CODE>java.awt.Button</CODE>
类文档中包含按钮图像 <CODE>button.gif</CODE>，则可将该文件放入
<CODE>/home/user/src/java/awt/doc-files/</CODE> 目录中。所有到未处理文件的链接都必须是硬编码的，因为
Javadoc 不查看这些文件 -- 它只是将目录及其全部内容复制到目的地。例如，<CODE>Button.java</CODE>
文档注释中的链接可能类似如下：</P><PRE> /**
* 该按钮类似如下：
* <img src="doc-files/Button.gif">
*/
</PRE></BLOCKQUOTE>
<P><BR><!-- ====================== GENERATED FILES ========================= --><A
name=generatedfiles></A></P>
<H2>生成的文件</H2>
<BLOCKQUOTE>
<P>缺省地，javadoc 使用标准 doclet 生成 HTML 格式文档。该 doclet 生成下列类型的文件（其中每个 HTML
“页”相应于一个单独的文件）。注意 javadoc 生成具有二种名字的文件： 用类/接口命名的文件，和不用类/接口命名的文件（例如
<CODE>package-summary.html</CODE>）。后一组中的文件包括下划线（以防止与前一组中的文件名冲突）。</P>
<P><B>基本内容页</B>
<UL>
<LI>为生成其文档的每个类或接口生成<B>类或接口页</B>（<I>classname</I><CODE>.html</CODE>）。<A
name=packagesummary></A>
<LI>为生成其文档的每个包生成<B>包页</B>（<CODE>package-summary.html</CODE>）。Javadoc
将在其中包含源树中包目录中的 <CODE>package.html</CODE> 文件中提供的任何 HTML 文本。<A
name=overviewsummary></A>
<LI>整个包集的<B>概述页</B>（<CODE>overview-summary.html</CODE>）。它是生成的文档的首页。Javadoc
将在其中包含用 <A
href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#overview"><CODE>-overview</CODE></A>
选项指定的文件中提供的任何 HTML 文本。（注意在有些情况下未生成概述页，详情参见 <A
href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#javadocoutput">Javadoc
输出</A>。） </LI></UL>
<P><B>交叉参考页</B>
<UL>
<LI><B>整个包集的类层次页</B>（<CODE>overview-tree.html</CODE>）。要查看它，可以单击导航栏上的“概述”，然后单击“树”。
<LI><B>整个包的类层次页</B>（<CODE>package-tree.html</CODE>）。要查看它，可转到特定包、类或接口页；单击“树”显示该包的层次。
<LI>每个包的<B>“用法”页</B>（<CODE>package-use.html</CODE>）和每个类和接口的单独页（<CODE>class-use/</CODE><I>classname</I><CODE>.html</CODE>）。该页描述了使用给定类、接口或包的任何部分的包、类、方法、构造函数和域。给定一个类或接口
A，其“用法”页包括 A 的子类、声明为 A 的域、返回 A 的方法以及具有 A
类型参数的方法和构造函数。要访问该页，可首先转到包、类或接口，然后在导航栏中单击“用法”链接。
<LI><B>不鼓励使用的 API
页</B>（<CODE>deprecated-list.html</CODE>），列出所有不鼓励使用的名字。（通常由于改进的原因不推荐使用不鼓励使用的名字，并提供了替代的名字。不鼓励使用的
API 在未来的实现中可能删除。）
<LI><B>序列化形式页</B>（<CODE>serialized-form.html</CODE>），提供关于可序列化或可外部化类的信息。每个这种类具有其序列化域和方法的描述。该信息对于重实现人员有用，使用
API 的开发人员一般不感兴趣。尽管在导航栏中没有其链接，但是可通过转到任何序列化类并单击类描述的“参见”部分中的“序列化形式”，获得该信息。
<LI>所有类、接口、构造函数、域及方法名的 <B>索引</B>（<CODE>index-*.html</CODE>），按字母次序排列。它为
Unicode 进行了国际化，并可生成为单个文件或为每个开始字符（例如英语中的 A - Z）生成一个单独的文件。 </LI></UL>
<P><B>支持文件</B>
<UL>
<LI><B>帮助页</B>（<CODE>help-doc.html</CODE>），它描述导航栏和上述各页。可使用 <A
href="http://www.iplab.is.tsukuba.ac.jp/~liuxj/jdk1.2/zh/docs/tooldocs/solaris/javadoc.html#helpfile"><CODE>-helpfile</CODE></A>
用自己的自定义帮助文件覆盖缺省帮助文件。
<LI><B>index.html 文件</B>，创建用于显示的 HTML 框架。加载该文件可以用框架显示首页。该文件本身不包含文本内容。
<LI>包含包、类和接口列表的几个 <B>框架文件</B>（<CODE>*-frame.html</CODE>），在显示 HTML 框架时使用。
<LI><B>包列表</B> 文件（<CODE>package-list</CODE>），通过 <CODE>-link</CODE> 和
<CODE>-linkoffline</CODE> 选项使用。它是文本文件，而不是 HTML 文件，并且不能通过任何链接到达。
<LI><B>样式表单</B>
文件（<CODE>stylesheet.css</CODE>），它用于控制生成页面上的颜色数、字体、字体大小、字体样式和定位。 </LI></UL>
<P><A name=htmlframes></A><B>HTML 框架</B> </P>
<P>Javadoc 将生成两个或三个 HTML 框架，如下图中所示。当将源文件（*.java）或单个包名作为参数传递到 javadoc
命令中时，它将仅在左边栏中创建一个框架（C） -- 类列表。当给 javadoc
传递两个或多个包名时，它将创建第三个框架（P）（列出所有包）以及一个概述页（Detail）。可通过在“无框架”链接上单击或在
overview-summary.html 进入，从而绕过框架。</P>
<P>如果您不熟悉 HTML 框架，则应该记住框架可具有
<I>焦点</I>，以进行打印或滚动。要使框架具有焦点，可在其上单击。然后在许多浏览器中，箭头键和翻页键将滚动该框架，而打开菜单命令将打印它。</P><PRE> ------------ ------------
|C| Detail | |P| Detail |
| | | | | |
| | | |-| |
| | | |C| |
| | | | | |
| | | | | |
------------ ------------
javadoc *.java javadoc java.lang java.awt
</PRE>
<P>根据是否想要 HTML 框架，可加载下列两个文件之一作为开始页：
<UL>
<LI><CODE>index.html</CODE>（需要框架）
<LI><CODE>overview-summary.html</CODE>（不需要框架） </LI></UL>
<P><A name=filestructure></A></P><B>
<P>生成的文件结构</B> </P>
<P>生成的类和接口按与 Java 源文件和类文件相同的目录层次组织。该结构是每个子包一个目录。</P>
<P>例如，为 <CODE>java.applet.Applet</CODE> 类生成的文档将位于
<CODE>java/applet/Applet.html</CODE>。java.applet 包的文件结构也是一样，假定目的目录命名为
<CODE>apidocs</CODE>。如前所述，包含词“frame”的所有文件将出现在左上框架或左下框架中。所有其他 HTML
文件出现在右边框架中。</P>
<BLOCKQUOTE>
<P>注意 - 目录用 <B>粗体</B> 显示。星号（<CODE>*</CODE>）表示当 javadoc
的参数为源文件（*.java）而不是包名时<I>省略</I>的文件和目录。另外当参数为源文件名时，将创建
<CODE>package-list</CODE> 但是它为空。文档文件目录将不出现在目的地中，除非它在源树中存在。</P></BLOCKQUOTE><PRE>
<B>apidocs</B> 顶级目录
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 选项创建的缺省索引
<B>index-files</B> 用 -splitindex 选项创建的目录
index-<number>.html 用 -splitindex 选项创建的索引文件
package-list 列出包名，仅用于解析外部引用
stylesheet.css HTML 样式表单，用于定义字体、颜色和位置
<B>java</B> 子包目录
<B>applet</B> 子包目录
Applet.html Applet 类页
AppletContext.html AppletContext 接口页
AppletStub.html AppletStub 接口页
AudioClip.html AudioClip 接口页
* package-summary.html 列出带首句类概览的类
* package-frame.html 列出该包中的类，用于左下框架
* package-tree.html 列出该包的类层次
package-use 列出使用该包的地方
<B>doc-files</B> 保存图像和示例文件的目录
<B>class-use</B> 保存 API 用法页的目录
Applet.html Applet 类用法页
AppletContext.html AppletContext 接口用法页
AppletStub.html AppletStub 接口用法页
AudioClip.html AudioClip 接口用法页
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -