從 Java 源文件生成 API 文檔 HTML 頁。
javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]參數(shù)可按任意次序排列。
- options
- 命令行選項，如本文檔中所指定。要了解 javadoc 選項的典型用法，參見實際示例。
packagenames- 一系列包的名字，用空格分隔，例如
java.lang java.lang.reflect java.awt。必須分別指定想要為之建立文檔的每一個包。Javadoc 不遞歸地作用于子包。不允許使用通配符，如（*）。參見示例 - 建立包的文檔sourcefiles- 一系列源文件名，用空格分隔。源文件名可包括路徑和通配符如（*）。例如：
Button.java /home/src/java/awt/Graphics*.java參見示例 - 建立類的文件。還可混合包名和源文件，如 示例 - 建立包和類的文檔 中所示。- @files
- 以任何次序包含包名和源文件的一個或多個文件。
Javadoc 解析 Java 源文件中的聲明和文檔注釋，并產(chǎn)生相應(yīng)的 HTML 頁（缺?。?，描述公有類、保護類、內(nèi)部類、接口、構(gòu)造函數(shù)、方法和域。
可對 整個包、單個源文件 或 二者 運行 Javadoc。在第一種情況中，將一系列包名作為參數(shù)傳遞給
javadoc。在第二種情況中，傳遞一系列源（.java）文件名。在本文檔最后給出了 示例。在實現(xiàn)時，Javadoc 要求且依賴于 java 編譯器完成其工作。Javadoc 調(diào)用部分
javac編譯聲明部分，忽略成員實現(xiàn)。它建立類的內(nèi)容豐富的內(nèi)部表示，包括類層次和“使用”關(guān)系，然后從中生成 HTML。Javadoc 還從源代碼的 文檔注釋 中獲得用戶提供的文檔。實際上，Javadoc 將在不帶方法體的純 stub 文件的
.java源文件上運行。這意味著可以創(chuàng)建 API 的最早期階段，在編寫任何代碼之前，就可編寫文檔注釋并運行 Javadoc。依賴編譯器可以確保 HTML 輸出完全對應(yīng)于實際實現(xiàn)，這些實現(xiàn)可能有賴于隱式的（而非顯式的）源代碼。例如，Javadoc 將建立在
.class文件中存在但在源代碼中不存在的 缺省構(gòu)造函數(shù)（Java 語言規(guī)范 的第 8.6.7 節(jié)）的文檔。當(dāng) Javadoc 建立其內(nèi)部文檔結(jié)構(gòu)時，它將加載所有引用的類。由于這一點，Javadoc 必須能查找到所有引用的類，包括引導(dǎo)類、擴展類和用戶類。有關(guān)詳細信息，參見如何查找類。一般而言，所創(chuàng)建的類必須加載為擴展或位于 Javadoc 的類路徑中。
Javadoc Doclets
可使用 doclets 自定義 Javadoc 輸出的內(nèi)容和格式。Javadoc 具有一個缺省的“內(nèi)嵌”doclet，叫作標(biāo)準(zhǔn) doclet，它生成 HTML-格式的 API 文檔。用戶可修改或擴展標(biāo)準(zhǔn) doclet，或編寫自己的 doclet 以生成 HTML、XML、MIF、RTF 或想要的任何輸出格式。關(guān)于 doclets 及其用法的信息位于下列位置：
當(dāng)沒有用 -doclet 命令行選項指定自定義 doclet 時，Javadoc 將使用缺省的標(biāo)準(zhǔn) doclet。不管使用哪個 doclet，javadoc 工具都有幾個命令行選項可用。標(biāo)準(zhǔn) doclet 還添加了額外的命令行選項集。二個選項集都將在下面的 選項 一節(jié)中介紹。
相關(guān)文檔
- 有關(guān) Javadoc 1.2 中增強功能的詳細信息，參見 Javadoc 增強。
- 有關(guān)常問問題的答案、關(guān)于 Javadoc 相關(guān)工具的信息以及 bug 的解決方案，參見 Javadoc FAQ。
- 有關(guān)如何編寫文檔注釋的信息，參見 如何為 Javadoc 編寫文檔注釋。
術(shù)語
在 Javadoc 環(huán)境中，有些術(shù)語具有特定的意義：
- 生成的文檔
- 由 javadoc 工具根據(jù) Java 源代碼中文檔注釋生成的文檔。缺省的生成文檔是 HTML 格式，并由標(biāo)準(zhǔn) doclet 生成。
- 名字
- Java 語言中的名字，通常為包、類、接口、域、構(gòu)造函數(shù)或方法的名字。名字可以是完全限定的，例如
java.lang.String.equals(java.lang.Object)，也可是部分限定的，例如equals(Object)。
- 帶文檔的類
- 在 javadoc 運行期間為之生成了全部文檔的類和接口。要生成文檔，源文件必須可用，并且其源文件名或包名必須傳遞到 javadoc 命令中。我們還將這些類稱為在 javadoc 運行中包含的類，或包含的類。
- 引用類
- 在帶文檔的類和接口的定義（實現(xiàn)）中顯式引用的類和接口。引用的例子包括返回類型、參數(shù)類型、強制轉(zhuǎn)換類型、已實現(xiàn)接口、導(dǎo)入類，等等。在文檔注釋（例如 @see 標(biāo)記）中引用的類不算作引用類。當(dāng) Javadoc 運行時，它將 javadoc 引導(dǎo)類路徑和類路徑中所有的引用類加載到內(nèi)存中（對于沒有找到的引用類，Javadoc 將顯示“類未找到”警告信息）。 Javadoc 可從類文件中獲得足夠的信息，以確定其存在性及其成員的全限定名字。
- 外部引用類
- 在 javadoc 運行期間沒有生成其文檔的引用類。也就是說，這些類對于該次 javadoc 運行是外部的。文檔中名字到這些類的鏈接稱為外部引用或外部鏈接。例如，如果僅對
java.awt包運行 javadoc，則java.lang中的任何類（如 Object）都是外部引用類。可使用-link選項鏈接外部引用類。
Javadoc 將根據(jù)四種不同的“源”文件生成輸出： Java 語言源文件（.java）、包注釋文件、概述注釋文件和其他未處理文件。下面介紹了后三種類型。
包注釋文件
每個包具有它自己的文檔注釋，保存在其自己的“源”文件中，Javadoc 將把它合并到生成的包概覽頁中。通常可在這個注釋中包括適用于整個包的任何文檔。
要創(chuàng)建包注釋文件，必須將它命名為
package.html并將它與.java文件一起放在源樹中的包目錄中。Javadoc 將自動在該位置查找該文件名。注意該文件名對于所有包都是相同的。包注釋文件的內(nèi)容是一個大文檔注釋，用 HTML 編寫，像所有其他注釋一樣，但有一個例外： 文檔注釋不應(yīng)該包括注釋分隔符
/**和*/或前導(dǎo)星號。在編寫注釋時，第一句應(yīng)該是關(guān)于包的概覽，并且在<body>和第一句之間不應(yīng)該插入任何標(biāo)題或其他文本?？砂?package 標(biāo)記；與所有文檔注釋一樣，除了{@link}之外的所有標(biāo)記都應(yīng)該位于描述之后。如果添加@see標(biāo)記，則它必須是全限定名字。當(dāng) Javadoc 運行時，它將自動查找該文件；如果找到，則 Javadoc 做下列事情：
- 復(fù)制
<body>和</body>標(biāo)記之間的全部內(nèi)容以進行處理。- 處理存在的任何包標(biāo)記。
- 在它生成的包概覽頁底部插入處理后的文本，例如 包概覽。
- 將包注釋的第一句復(fù)制到包概覽頁和概述頁（例如概述概覽）的頂部。確定語句結(jié)尾用的規(guī)則相同確定類和成員描述第一個語句的相同規(guī)則確定。
概述注釋文件
每個要為之建立文檔的應(yīng)用程序或包集可以有它自己的概述文檔注釋，保存在其自己的“源”文件中，Javadoc 將把它合并到生成的概述頁中。在該注釋中通?？砂ㄟm用于整個應(yīng)用程序或包集的任何文檔。
要創(chuàng)建概述注釋文件，可將該文件命名為想要的任何名字（通常為
overview.html）并將它放置在任何地方（通常位于源樹的最頂層中）。注意對于相同源文件集可有多個概述注釋文件，以用于對不同包集多次運行 javadoc。例如，如果java.applet包的源文件包含在C:\user\src\java\applet目錄中，則可創(chuàng)建概述注釋文件C:\user\src\overview.html。概述注釋文件的內(nèi)容是一個大文檔注釋，用 HTML 編寫，與前面介紹的包注釋文件類似。有關(guān)詳細內(nèi)容，參見描述。在編寫注釋時，要重新循環(huán)，第一句應(yīng)該是關(guān)于應(yīng)用程序或包集的概覽，并且在
<body>和第一句之間不要插入標(biāo)題或任何其他文本。可包括 概述標(biāo)記；與所有文檔注釋一樣，除了{@link}之外的所有標(biāo)記都就位于描述之后。如果添加@see標(biāo)記，則它必須是全限定名字。當(dāng)運行 Javadoc 時，可用 -overview 選項指定概述注釋文件。然后將以與包注釋文件類似的方法處理該文件。
- 復(fù)制
<body>和</body>標(biāo)記之間的全部內(nèi)容以進行處理。- 處理存在任何 概述標(biāo)記。
- 將處理過后的文本插入到生成的概述頁（例如 概述概覽）的底部。
- 將概述注釋的第一句復(fù)制到概述概覽頁的頂部。
其他未處理文件
還可在源文件中包括想要 Javadoc 復(fù)制到目的目錄中的任何其他文件。這通常包括圖形文件、示例 Java 源文件（.java）和類文件（.class）以及其內(nèi)容遠超過常規(guī) Java 源文件文檔注釋的獨立 HTML 文件。
要包括未處理文件，請將它們放入一個叫作
doc-files的目錄中，它可以是任何包目錄的子目錄。每個包可以有使用一個這種子目錄。例如，如果想要在java.awt.Button類文檔中包含按鈕圖像button.gif，則可將該文件放入/home/user/src/java/awt/doc-files/目錄中。所有到未處理文件的鏈接都必須是硬編碼的，因為 Javadoc 不查看這些文件 -- 它只是將目錄及其全部內(nèi)容復(fù)制到目的地。例如，Button.java文檔注釋中的鏈接可能類似如下：/** * 該按鈕類似如下： * <img src="doc-files/Button.gif"> */
缺省地，javadoc 使用標(biāo)準(zhǔn) doclet 生成 HTML 格式文檔。該 doclet 生成下列類型的文件（其中每個 HTML “頁”相應(yīng)于一個單獨的文件）。注意 javadoc 生成具有二種名字的文件： 用類/接口命名的文件，和不用類/接口命名的文件（例如
package-summary.html）。后一組中的文件包括下劃線（以防止與前一組中的文件名沖突）。基本內(nèi)容頁
- 為生成其文檔的每個類或接口生成類或接口頁（classname
.html）。- 為生成其文檔的每個包生成包頁（
package-summary.html）。Javadoc 將在其中包含源目錄樹中包目錄中的package.html文件中提供的任何 HTML 文本。- 整個包集的概述頁（
overview-summary.html）。它是生成的文檔的首頁。Javadoc 將在其中包含用 -overview 選項指定的文件中提供的任何 HTML 文本。（注意在有些情況下未生成概述頁，詳情參見 Javadoc 輸出。）交叉參考頁
- 整個包集的類層次頁（
overview-tree.html）。要查看它，可以單擊導(dǎo)航欄上的“概述”，然后單擊“樹”。- 整個包的類層次頁（
package-tree.html）。要查看它，可轉(zhuǎn)到特定包、類或接口頁；單擊“樹”顯示該包的層次。- 每個包的“用法”頁（
package-use.html）和每個類和接口的單獨頁（class-use/classname.html）。該頁描述了使用給定類、接口或包的任何部分的包、類、方法、構(gòu)造函數(shù)和域。給定一個類或接口 A，其“用法”頁包括 A 的子類、聲明為 A 的域、返回 A 的方法以及具有 A 類型參數(shù)的方法和構(gòu)造函數(shù)。要訪問該頁，可首先轉(zhuǎn)到包、類或接口，然后在導(dǎo)航欄中單擊“用法”鏈接。- 不鼓勵使用的 API 頁（
deprecated-list.html），列出所有不鼓勵使用的名字。（通常由于改進的原因不推薦使用不鼓勵使用的名字，并提供了替代的名字。不鼓勵使用的 API 在未來的實現(xiàn)中可能刪除。）- 序列化形式頁（
serialized-form.html），提供關(guān)于可序列化或可外部化類的信息。每個這種類具有其序列化域和方法的描述。該信息對于重實現(xiàn)人員有用，使用 API 的開發(fā)人員一般不感興趣。盡管在導(dǎo)航欄中沒有其鏈接，但是可通過轉(zhuǎn)到任何序列化類并單擊類描述的“參見”部分中的“序列化形式”，獲得該信息。- 所有類、接口、構(gòu)造函數(shù)、域及方法名的 索引（
index-*.html），按字母次序排列。它為 Unicode 進行了國際化，并可生成為單個文件或為每個開始字符（例如英語中的 A - Z）生成一個單獨的文件。支持文件
- 幫助頁（
help-doc.html），它描述導(dǎo)航欄和上述各頁。可使用 -helpfile 用自己的自定義幫助文件覆蓋缺省幫助文件。- index.html 文件，創(chuàng)建用于顯示的 HTML 框架。加載該文件可以用框架顯示頭版。該文件本身不包含文本內(nèi)容。
- 包含包、類和接口列表的幾個框架文件（
*-frame.html），在顯示 HTML 框架時使用。- 包列表 文件（
package-list），通過-link和-linkoffline選項使用。它是文本文件，而不是 HTML 文件，并且不能通過任何鏈接到達。- 樣式表單 文件（
stylesheet.css），它用于控制生成頁面上的顏色數(shù)、字體、字體大小、字體樣式和定位。HTML 框架
Javadoc 將生成兩個或三個 HTML 框架，如下圖中所示。當(dāng)將源文件（*.java）或單個包名作為參數(shù)傳遞到 javadoc 命令中時，它將僅在左邊欄中創(chuàng)建一個框架（C） -- 類列表。當(dāng)給 javadoc 傳遞兩個或多個包名時，它將創(chuàng)建第三個框架（P）（列出所有包）以及一個概述頁（Detail）?？赏ㄟ^在“無框架”鏈接上單擊或在 overview-summary.html 進入，繞過框架。
如果您不熟悉 HTML 框架，則應(yīng)該記住框架可具有焦點，以進行打印或滾動。要使框架具有焦點，可在其上單擊。然后在許多瀏覽器中，箭頭鍵和翻頁鍵將滾動該框架，而打印菜單命令將打印它。
------------ ------------ |C| Detail | |P| Detail | | | | | | | | | | |-| | | | | |C| | | | | | | | | | | | | | ------------ ------------ javadoc *.java javadoc java.lang java.awt根據(jù)是否想要 HTML 框架，可加載下列兩個文件之一作為開始頁：
index.html（需要框架）overview-summary.html（不需要框架）
生成的文件結(jié)構(gòu)
生成的類和接口按與 Java 源文件和類文件相同的目錄層次組織。該結(jié)構(gòu)是每個子包一個目錄。
例如，為
java.applet.Applet類生成的文檔將位于java\applet\Applet.html。java.applet 包的文件結(jié)構(gòu)也是一樣，假定目的目錄命名為apidocs。如前所述，包含詞“frame”的所有文件將出現(xiàn)在左上框架或左下框架中。所有其他 HTML 文件出現(xiàn)在右邊框架中。注意 - 目錄用 粗體 顯示。星號（
*）表示當(dāng) javadoc 的參數(shù)為源文件（*.java）而不是包名時省略的文件和目錄。另外當(dāng)參數(shù)為源文件名時，將創(chuàng)建package-list但是它為空。文檔文件目錄將不出現(xiàn)在目的地中，除非它在源目錄樹中存在。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 選項創(chuàng)建的缺省索引 index-files 用 -splitindex 選項創(chuàng)建的目錄 index-<number>.html 用 -splitindex 選項創(chuàng)建的索引文件 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 接口用法頁
注釋源代碼
可以在源代碼中任何實體（類、接口、方法、構(gòu)造函數(shù)或域）聲明的前面包括文檔注釋。它們也稱為 Javadoc 注釋，并且文件必須用 HTML 編寫，它們應(yīng)使用 HTML 實體并可使用 HTML 標(biāo)記。用戶可使用自己瀏覽器支持的任何 HTML 版本；我們編寫的標(biāo)準(zhǔn) doclet 可在其它地方（文檔注釋外部）生成 HTML 3.2-兼容代碼，其中包括級聯(lián)樣式表單和框架（由于使用框架集，我們在每個生成文件前面添加了“HTML 4.0”）。
例如，小于 (
<) 和大于 (>) 符號的實體應(yīng)該寫為<和>。類似地，與符號（&）應(yīng)該寫為&。在下面的示例中顯示了粗體 HTML 標(biāo)記 <b>。下面是文檔注釋：
/** * 這是 <b>doc</b> 注釋。 * @see java.lang.Object */文檔注釋由開始注釋的字符
/**和結(jié)束注釋的字符*/之間的字符組成。文本分成一行或多行。當(dāng) javadoc 解析文檔注釋時，將去掉每行中的前導(dǎo)星號（*）；初始星號（*）字符前面的空格和制表字符也丟棄。如果省略一行上的前導(dǎo)星號，則所有前導(dǎo)空格將被去除。（在某種程度上，可以忽略前導(dǎo)星號。由于省略前導(dǎo)星號導(dǎo)致問題的一種情況是用<pre>標(biāo)記格式化多行的縮進時，例如樣本代碼所示。沒有前導(dǎo)星號，生成文檔中的縮進將丟失，因為前導(dǎo)空格被刪除。）每個文檔注釋的首句應(yīng)該為概覽名，包含所聲明實體的完整簡要描述。該語句在第一個句號處結(jié)束后跟空格、制表或行結(jié)束符，或在第一個 標(biāo)記 處結(jié)束。Javadoc 將首句復(fù)制到 HTML 頁頂部的成員概覽中。
文檔注釋只有在位于類、接口、構(gòu)造函數(shù)、方法或域聲明前面才能被識別。每個聲明只有一個文檔注釋為 Javadoc 工具所識別。
當(dāng)在文檔注釋中嵌入 HTML 標(biāo)記時，不應(yīng)使用 HTML 標(biāo)題標(biāo)記例如 <H1> 和 <H2>，因為 Javadoc 創(chuàng)建完全結(jié)構(gòu)化的文檔，而這些標(biāo)記將會干擾所生成文檔的格式。
以字符
@開始的第一行文檔注釋將結(jié)束描述并開始標(biāo)記段落部分。上例中的@see標(biāo)記就是這種標(biāo)記段落。有關(guān)文檔注釋的規(guī)范，參見 James Gosling、Bill Joy 和 Guy Steele 所著書籍 Java 語言規(guī)范 中的第 18 章“文檔注釋”。
Javadoc 解析 Java 文檔注釋中嵌入的特殊標(biāo)記。這些文檔標(biāo)記可幫助自動從源代碼生成完整的格式化 API。標(biāo)記用“at”符號（
@）開頭，并區(qū)分大小寫 -- 必須按照正確大小寫字母輸入它們。標(biāo)記必須從一行的開頭開始（位于任何前導(dǎo)空格和可選星號之后），否則它將被視為普通文本。按規(guī)定應(yīng)將相同名字的標(biāo)記放在一起。例如，將所有@see標(biāo)記放在一起。有關(guān)我們將在未來版本中引入的標(biāo)記的信息，參見 提議標(biāo)記。
當(dāng)前標(biāo)記有：
標(biāo)記 引入該標(biāo)記的 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
@authorname-text- 當(dāng)使用 -author 選項時，用指定的 name-text 在生成文檔中添加“Author”項。文檔注釋可包含多個
@author標(biāo)記?？梢詫γ總€@author指定一個或多個名字。在前一種情況中，Javadoc 將在名字之間插入逗號（,）和空格。在后一種情況下，將全部文本復(fù)制到生成文檔中而不進行解析。如果想要用逗號以外的本地化名字分隔符，則應(yīng)每行使用這個名字。
@deprecateddeprecated-text- 添加注釋，指示不應(yīng)再使用該 API（盡管它仍可用）。Javadoc 將 deprecated-text 移動到描述前面，用斜體顯示，并在它前面添加粗體警告： “不鼓勵使用”。
deprecated-text 的首句至少應(yīng)該告訴用戶什么時候開始不鼓勵使用該 API 及使用什么替代它。Javadoc 僅將首句復(fù)制到概覽部分和索引中。后面的語句還可解釋為什么不鼓勵使用它。還應(yīng)包括一個指向替代 API 的
{@link}標(biāo)記（對于 Javadoc 1.2 或更新版本）：
- 對于 Javadoc 1.2，使用
{@link}標(biāo)記。這將在需要的地方創(chuàng)建內(nèi)嵌鏈接。例如：/** * @deprecated 在 JDK 1.1 中，被 {@link #setBounds(int,int,int,int)} 取代。 */- 對于 Javadoc 1.1，標(biāo)準(zhǔn)格式是為每個
@deprecated標(biāo)記創(chuàng)建@see標(biāo)記（它不能內(nèi)嵌）。有關(guān)不鼓勵使用的信息，參見 @deprecated 標(biāo)記。
@exceptionclass-name description@exception標(biāo)記是 @throws 的同義標(biāo)記。
{@linkname label}- 插入指向指定 name 的內(nèi)嵌鏈接。該標(biāo)記中 name 和 label 的語法與
@see標(biāo)記完全相同，如下所述，但是它產(chǎn)生內(nèi)嵌鏈接而不是在“參見”部分中放置鏈接。該標(biāo)記用花括號開始并用花括號結(jié)束，以使它區(qū)別于其他內(nèi)嵌文本。如果在標(biāo)簽內(nèi)需要使用“}”，則請使用 HTML 實體表示法 }對于一個語句中所允許的 {@link} 標(biāo)記數(shù)目沒有限制?？梢栽谖臋n注釋的描述部分或任何標(biāo)記（例如 @deprecated、@return 或 @param）的文本部分中使用該標(biāo)記。
例如，下面是一個引用
getComponentAt(int, int)方法的注釋：使用 {@link #getComponentAt(int, int) getComponentAt} 方法。根據(jù)它，標(biāo)準(zhǔn) doclet 將生成如下 HTML（假定它引用相同包中另一個類）：
使用 <a href="Component.html#getComponentAt(int, int)">getComponentAt</a> 方法。它在 web 頁上顯示為：
使用 getComponentAt 方法。
@paramparameter-namedescription- 給“參數(shù)”部分添加參數(shù)。描述可繼續(xù)到下一行。
@returndescription- 用 description 文本添加“返回”部分。該文本應(yīng)描述值的返回類型和容許范圍。
@seereference- 添加“參見”標(biāo)題，其中有指向 reference 的鏈接或文本項。文檔注釋可包含任意數(shù)目的
@see標(biāo)記，它們都分組在相同標(biāo)題下。@see標(biāo)記具有三種變體；下面的第三種形式是最常用的形式。
@see"string" 注意 - 該形式在 JDK 1.2 沒有用。它不打印引用文本。- 為 string 添加文本項。不產(chǎn)生鏈接。string 是通過該 URL 不可用的書籍或其他信息引用。Javadoc 通過查找第一個字符為雙引號（
"）的情形來區(qū)分它與前面的情況。例如：@see "Java 編程語言"這將生成如下文本：
- 參見：
- "Java 編程語言"
@see<a href="URL#value">label</a>- 添加 URL#value 定義的鏈接。其中 URL#value 是相對 URL 或絕對 URL。Javadoc 通過查找第一個字符小于符號（
<）區(qū)分它與其他情況。例如：@see <a href="spec.html#section">Java 規(guī)范</a>這將生成如下鏈接：
- 參見：
- Java Spec
@seepackage.class#member label- 添加帶可見文本 label 的鏈接，它指向 Java 語言中指定名字的文檔。其中 label 是可選的；如果省略，則名字將作為可見文本出現(xiàn)，而且嵌入在
<code>HTML 標(biāo)記中。當(dāng)想要縮寫可見文本或不同于名字的可見文本時，可使用 label。
- package.class
#member 是 Java 語言中的任何有效名字 -- 包名、類名、接口名、構(gòu)造函數(shù)名、方法名或域名 -- 除了用 hash 字符（#）取代成員名前面的點之外。如果該名字位于帶文檔的類中，則 Javadoc 將自動創(chuàng)建到它的鏈接。要創(chuàng)建到外部引用類的鏈接，可使用 -link 選項。使用另兩種@see形式的任何一種引用不屬于引用類的名字的文檔。第一個參數(shù)將在 指定名字 中詳細介紹。- label 是可選文本，它是鏈接的可見標(biāo)簽。label 可包含空格。如果省略 label，則將顯示 package.class.member，并相對于當(dāng)前類和包適當(dāng)縮短。-- 參見 如何顯示名字。
- 空格是 package.class
#member 和 label 之間的分界符。括號內(nèi)的空格不表示標(biāo)簽的開始，因此在方法各參數(shù)之間可使用空格。示例 - 在該示例中，
Character類中的@see標(biāo)記引用String類中的equals方法。該標(biāo)記包括兩個參數(shù)： 名字“String#equals(Object)”和標(biāo)簽“equals”。./** * @see String#equals(Object) equals */標(biāo)準(zhǔn) doclet 將產(chǎn)生類似如下的 HTML 文檔：
<dl> <dt><b>參見：</b> <dd><a href="../../java/lang/String#equals(java.lang.Object)">equals</a> </dl>它在瀏覽器中看起來像如下內(nèi)容，其中標(biāo)簽是可見鏈接文本：
- 參見：
- equals
指定名字 - package.class
#member 名可以是全限定的，例如java.lang.String#toUpperCase()，也可以不是全限定的，例如String#toUpperCase()或#toUpperCase()。如果不是全限定的，則 Javadoc 使用正常 Java 編譯器搜索次序查找它，在 @see 的搜索次序 中將進一步介紹。名字可以在括號內(nèi)包含空格，例如在方法參數(shù)之間。當(dāng)然使用較短的“部分限定”名字的優(yōu)點是鍵入更少，并且源代碼中的混亂更少。下表顯示的不同的名字形式，其中 Class 可以為類或接口，Type 可以為類、接口、數(shù)組或 基本數(shù)據(jù)類型，而 method 可以為方法或構(gòu)造函數(shù)。
@seepackage.class#member 的典型形式引用當(dāng)前類的成員 @see#field@see#method(Type, Type,...)@see#method(Type argname, Type argname,...)
引用當(dāng)前包或?qū)氚械钠渌?/b>@seeClass#field@seeClass#method(Type, Type,...)@seeClass#method(Type argname, Type argname,...)@seeClass
引用其他包（全限定）@seepackage.Class#field@seepackage.Class#method(Type, Type,...)@seepackage.Class#method(Type argname, Type argname,...)@seepackage.Class@seepackage下述說明適用于上表：
- 第一套形式（沒有類和包）將導(dǎo)致 Javadoc 僅搜索當(dāng)前類層次。它將查找當(dāng)前類或接口、其父類或超接口、或其包含類或接口的成員（搜索步驟 1-3）。它不會搜索當(dāng)前包的其余部分或其他包（搜索步驟 4-5）。
- 如果任何方法或構(gòu)造函數(shù)輸入為不帶括號的名字，例如
getValue，且如果沒有具有相同名字的域，則 Javadoc 將正確創(chuàng)建到它的鏈接，但是將顯示警告信息，提示添加括號和參數(shù)。如果該方法被重載，則 Javadoc 將鏈接到它搜索到的第一個未指定方法。- 對于所有形式，內(nèi)部類必須指定為 outer
.inner，而不是簡單的 inner。- 如上所述，hash 字符（
#）而不是點（.）用于分隔類和成員。這使 Javadoc 可正確解析，因為點還用于分隔類、內(nèi)部類、包和子包。當(dāng) hash 字符（#）是第一個字符時，它是絕對不可少的。但是，在其他情況下，Javadoc 通常不嚴格，并允許在不產(chǎn)生歧義時使用點號，但是它將顯示警告。@see 的搜索次序 - Javadoc 將處理出現(xiàn)在源文件（.java）、包文件（package.html）或概述文件（overview.html）中的
@see標(biāo)記。在后兩種文件中，必須完全限定用@see提供的名字。在源文件中，可指定全限定或部分限定的名字。當(dāng) Javadoc 在
.java中遇到不是全限定的@see標(biāo)記時，它按照與 Java 編譯器相同的次序搜索指定名字（Javadoc 將不檢測名字空間二義性，因為它假定源代碼不會有這些錯誤） 搜索次序在 Java 語言規(guī)范 第六章“名字”中正式定義，由“內(nèi)部類規(guī)范”修改。Javadoc 在所有相關(guān)和導(dǎo)入類和包中搜索該名字。特別地，它按如下次序搜索：
- 當(dāng)前類或接口
- 任何包含類和接口，先搜索最近的
- 任何父類和超接口，先搜索最近的
- 當(dāng)前包
- 任何導(dǎo)入包、類和接口，按導(dǎo)入語句中的次序搜索
Javadoc 繼續(xù)對它遇到的每個類重復(fù)步驟 1-3 進行搜索，直到找到匹配項。這就是說，當(dāng)它搜索當(dāng)前類及其包含類 E 之后，它在搜索 E 的包含類之前先搜索 E 的父類。 在步驟 4 和 5 中，Javadoc 不按任何指定的次序（該次序取決于特定編譯器）搜索包中的類或接口。在步驟 5 中，Javadoc 將在 in java.lang 中查找，因為它是由所有程序自動導(dǎo)入的。
Javadoc 沒有必要在子類中查找，也沒有必要在其他包中查找，即使它們的文檔在同一次運行中生成。例如，如果
@see標(biāo)記位于java.awt.event.KeyEvent類中并引用java.awt包中的名字，則 javadoc 將不查找該包，除非該類導(dǎo)入它。如果顯示名字 - 如果省略 label，則將顯示 package.class.member。一般地，將相對于當(dāng)前類和包適當(dāng)縮短它。這里“縮短”是指僅顯示必要的名字，使之盡可能短。例如：
方法包含 @see Tag @see 標(biāo)記 顯示為 String.toUpperCase()@see String#toLowerCase()
（引用相同類的成員）toLowerCase()
（省略類名）String.toUpperCase()@see Character#toLowerCase(char)
（引用其他類的成員）Character.toLowerCase(char)
（包括類名）@see 示例
右邊的注釋顯示了當(dāng)@see標(biāo)記位于其他包（例如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 規(guī)范 @see "The Java Programming Language" // "Java 編程語言"@sincesince-text- 用 since-text 指定的內(nèi)容給生成文檔添加“Since”標(biāo)題。該文本沒有特殊內(nèi)部結(jié)構(gòu)。該標(biāo)記表示該改變或功能自 since-text 所指定的軟件版本之后就存在了。例如：
@since JDK1.1
@serialfield-description- 用于缺省可序列化域的文檔注釋中。
可選的 field-description 增強了文檔注釋對域的描述能力。該組合描述必須解釋該域的意義并列出可接受值。如需要，該描述可有多行。
應(yīng)該對自
Serializable類的最初版本之后添加的每個可序列化域添加@since標(biāo)記。要獲得私有類的序列化形式，可使用
-private選項。因而，要生成所有公共類和私有類的序列化形式，可用-private選項運行 javadoc。有關(guān)如何使用這些標(biāo)記的信息，以及相應(yīng)示例，參見 Java 對象序列化規(guī)范 中第 1.6 節(jié)“建立類的可序列化域和數(shù)據(jù)的文檔。
@serialFieldfield-name field-type field-description- 建立
Serializable類的serialPersistentFields成員的ObjectStreamField組件的文檔。應(yīng)該對每個ObjectStreamField使用一個@serialField標(biāo)記。
@serialDatadata-description- data-description 建立數(shù)據(jù)（尤其是
writeObject方法所寫入的可選數(shù)據(jù)和Externalizable.writeExternal方法寫入的全部數(shù)據(jù)）序列和類型的文檔，。
@serialData標(biāo)記可用于writeObject、readObject、writeExternal和readExternal方法的文檔注釋中。
@throwsclass-name description@throws和@exception標(biāo)記同義。用 class-name 和 description 文本給生成的文檔添加“拋出”子標(biāo)題。其中 class-name 是該方法可拋出的異常名。如果該類不是全限定的，則 Javadoc 使用 搜索次序 查找該類。
@versionversion-text- 當(dāng)使用 -version 選項時用 version-text 指定的內(nèi)容給生成文檔添加“版本”子標(biāo)題。該文本沒有特殊內(nèi)部結(jié)構(gòu)。文檔注釋最多只能包含一個
@version標(biāo)記。版本通常是指包含該類或成員的軟件（例如 JDK）版本。
下面介紹了在哪些地方可使用標(biāo)記。注意這四個標(biāo)記可用于所有文檔注釋中：
@see、@link、@since、@deprecated。
概述文檔標(biāo)記
概述標(biāo)記可出現(xiàn)在概述頁的文檔注釋中（該文檔通常位于叫作
overview.html的源文件中）。像在任何其他文檔注釋中一樣，這些標(biāo)記必須位于描述后面。注意 -
{@link}標(biāo)記在 JDK 1.2 的概述文檔中有一個 bug -- 文檔正確顯示，但沒有鏈接。
概述標(biāo)記
@see {@link} @since
包文檔標(biāo)記
包標(biāo)記可出現(xiàn)在包的文檔注釋中（該文檔位于叫作
package.html的源文件中）。
包標(biāo)記
@see {@link} @since @deprecated
類和接口文檔標(biāo)記
下面是可出現(xiàn)在類或接口的文檔注釋中的標(biāo)記。
類/接口標(biāo)記
@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 { ... }
域文檔標(biāo)記
下面是可出現(xiàn)在域文檔注釋中的標(biāo)記。
域標(biāo)記
@see {@link} @since @deprecated @serial @serialField 域注釋示例：
/** * 組件的 X 坐標(biāo)。 * * @see #getLocation() */ int x = 1263732;
構(gòu)造函數(shù)和方法文檔標(biāo)記
下面是可出現(xiàn)在構(gòu)造函數(shù)或方法的文檔注釋中的標(biāo)記。
方法/構(gòu)造函數(shù)標(biāo)記
@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命令，可指定一個或多個其中每行包含一個源文件名或包名的文件。在命令行中，采用 ‘@‘ 字符加上文件名的方法將它指定為文件列表。當(dāng) javadoc 遇到用字符‘@’開頭的參數(shù)時，它將操作該文件中的名字，仿佛這些名字位于命令行上一樣。例如，可以在名為
packages的文件中列出所有包名。該文件可能形如：com.mypackage1 com.mypackage2 com.mypackage3然后可用如下命令運行 javadoc：
C:> javadoc -d apidocs @packages
選項
javadoc 工具使用 doclets 確定其輸出。除非使用 -doclet 選項指定自定義 doclet ，否則 Javadoc 使用缺省的標(biāo)準(zhǔn) doclet。Javadoc 提供一套命令行選項，可用于任何 doclet -- 這些選項將在下面的子標(biāo)題 Javadoc 選項 中介紹。標(biāo)準(zhǔn) doclet 提供了一套額外的命令行選項，它們將在下面的子標(biāo)題 標(biāo)準(zhǔn) Doclet 提供的選項 中介紹。所有選項名都不區(qū)分大小寫，但是其參數(shù)可能區(qū)分大小寫。
選項包括：
Javadoc 選項
- -overview i>path\filename
- 指定 javadoc 應(yīng)該從 path\filename 所指定的“源”文件中獲取概述文檔，并將它放到概述頁中（
overview-summary.html）。其中 path\filename 是相對于-sourcepath的相對路徑名。盡管可對 filename 使用任何名字并將它放在 path 指定的任何地方，但是通常將它命令為
overview.html并將它放入包含最頂級包目錄的源目錄樹中。在該位置，建立包文檔時不需要 path，因為-sourcepath將指向該文件。例如，如果java.lang包的源目錄樹是/src/classes/java/lang/，則可以概述文件放到/src/classes/overview.html。參見 實際示例。有關(guān) path\filename 指定文件的信息，參見 概述注釋文件。
在一定情況下，將不產(chǎn)生概述頁。有關(guān)詳細信息，參見 HTML 框架。
- -public
- 只顯示公有類及成員。
- -protected
- 只顯示受保護的和公有的類及成員。這是缺省狀態(tài)。
- -package
- 只顯示包、受保護的和公有的類及成員。
- -private
- 顯示所有類和成員。
- -help
- 顯示聯(lián)機幫助，它將列出這些 javadoc 和 doclet 命令行選項。
- -doclet class
- 指定啟動用于生成文檔的 doclet 的類文件。該 doclet 定義了輸出的內(nèi)容和格式。如果未使用
-doclet選項，則 javadoc 使用標(biāo)準(zhǔn) doclet 生成缺省 HTML 格式。該類必須包含start(Root)方法。該啟動類的路徑由-docletpath選項定義。
- -docletpath classpathlist
- 指定 doclet 類文件的路徑，該類文件用
-doclet選項指定。如果 doclet 已位于搜索路徑中，則沒有必要使用該選項。
- -1.1
- 生成具有用 Javadoc 1.1 生成的文檔的外觀和功能的文檔。也就是說，頁的背景為灰色，用圖像做頁眉，使用 bullet 列表而不是表格，具有單級目的目錄結(jié)構(gòu)，不包含繼承 API，不使用 HTML 框架，并且不支持內(nèi)部類。該選項還將索引分割成每個字母一個文件。如果想要這種外觀，則該選項比 javadoc 1.1 優(yōu)越之處在于修正了一些錯誤。
不是所有選項都能用于
-1.1選項。為了查看哪些選項可用，可執(zhí)行：C:> javadoc -1.1 -help在該列表中顯示的
-footer選項在功能上與本頁中其他地方介紹的-bottom選項相同。而-title選項在功能上與-doctitle相同。
- -sourcepath sourcepathlist
- 當(dāng)將包名傳遞到
javadoc命令中時，指定查找源文件（.java）的搜索路徑。注意只有當(dāng)用 javadoc 命令指定包名時才能使用sourcepath選項 -- 它將不會定位傳遞到javadoc命令中的.java文件。如果省略-sourcepath，則 javadoc 使用類路徑查找源文件（參見 -classpath）。將 sourcepathlist 設(shè)置成正在生成其文檔的包的源樹的根目錄。例如，假定想要為叫作
com.mypackage的包建立文檔，其源文件位于：C:\user\src\com\mypackage\*.java在這種情況下，將把
sourcepath指定為C:\user\src，該目錄包含com\mypackage，然后提供包名com.mypackage：javadoc -sourcepath C:\user\src com.mypackage這是相當(dāng)容易記憶的，注意如果將源路徑和包名級聯(lián)到一起，并將點號改為斜杠“/”，則最后將得到該包的完整路徑：
C:\user\src\com\mypackage.
- -classpath classpathlist
- 指定 javadoc 將在其中查找 引用類 的路徑 -- 引用類是指帶文檔的類加上它們引用的任何類。Javadoc 將搜索指定路徑的所有子目錄。classpathlist 可以包含多個路徑，它們用分號分隔。有關(guān)如何指定 classpathlist，請遵循 類路徑 文檔中的指令。
如果省略
-sourcepath，則 Javadoc 使用-classpath查找源文件和類文件（為了向后兼容性）。因而，如果想要在不同的路徑中搜索源文件和類文件，則應(yīng)使用-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 環(huán)境變量（如果它已設(shè)置）。如果二者都未設(shè)置，則 Javadoc 將從當(dāng)前目錄中搜索類。有關(guān) Javadoc 如何使用
-classpath查找用戶類及相關(guān)擴展類和自舉類的深入介紹，參見 如何查找類。
- -bootclasspath classpathlist
- 指定自舉類所在路徑。它們名義上是 Java 平臺類。這個 bootclasspath 是 Javadoc 將用來查找源文件和類文件的搜索路徑的一部分。有關(guān)詳細信息，參見 如何查找類。在 classpathlist 中用分號（;）分隔目錄。
- -extdirs dirlist
- 指定擴展類所在的目錄。它們是任何使用 Java 擴展機制的類。這個 extdirs 是 Javadoc 將用來查找源文件和在文件的搜索路徑的一部分。有關(guān)詳細信息，參見上面的
-classpath。在 dirlist 中用分號（;）分隔目錄。
- -verbose
- 在 javadoc 運行時提供更詳細的信息。不使用 verbose 選項時，將顯示加載源文件、生成文檔（每個源文件一條信息）和排序的信息。verbose 選項導(dǎo)致打印額外的信息，指定解析每個 java 源文件的毫秒數(shù)。
- -locale language_country_variant
- 指定 javadoc 在生成文檔時使用的環(huán)境。該參數(shù)為環(huán)境名，如 java.util.Locale 文檔中所述，例如
en_US（英語，美國）或en_US_WIN（Windows 變量）。指定環(huán)境將導(dǎo)致 javadoc 為各種信息（導(dǎo)航欄中的字符串、列表和表格的標(biāo)題、幫助文件內(nèi)容、stylesheet.css 中的注釋，等等）選擇使用該環(huán)境的資源文件。它還指定按字母次序排序列表的排序次序，以及用于確定第一句結(jié)束的語句分隔符。它不決定帶文檔類的源文件中指定的文檔注釋文本的環(huán)境。
- -encoding name
- 指定源文件編碼名，例如
EUCJIS/SJIS。如果未指定該選項，則使用平臺缺省轉(zhuǎn)換器。
- -Jflag
- 將 flag 直接傳遞給運行 javadoc 的運行時系統(tǒng) java。注意在
J和 flag 之間不能有空格。例如，如果需要確保系統(tǒng)分配 32 兆內(nèi)存用于處理生成文檔，則應(yīng)按如下使用該標(biāo)志：牋
C:> javadoc -J-Xmx32m -J-Xms32m com.mypackage標(biāo)準(zhǔn) Doclet 提供的選項
- -d directory
- 指定 javadoc 保存生成的 HTML 文件的目的目錄。("d" 表示 "destination.") 省略該選項將導(dǎo)致把文件保存到當(dāng)前目錄中。其中 directory 可以是絕對路徑或相對當(dāng)前工作目錄的相對路徑。例如，下列代碼將生成
com.mypackage包的文檔并將結(jié)果保存在C:\user\doc\目錄中：C:> javadoc -d \user\doc com.mypackage
- -use
- 對每個帶文檔類和包包括一個“用法”頁。該頁描述使用給定類或包的任何 API 的包、類、方法、構(gòu)造函數(shù)和域。對于給定類 C，使用類 C 的任何東西將包括 C 的子類、聲明為 C 的域、返回 C 的方法以及具有 C 類型參數(shù)的方法和構(gòu)造函數(shù)。
例如，下面來看一下出現(xiàn)在 String 的“用法”頁上的內(nèi)容。
java.awt.Font類中的getName()方法返回類型String。因而，getName()使用String，從而可在String的“用法”頁上找到該方法。注意它只產(chǎn)生使用 API 的文檔，而不包括實現(xiàn)。如果方法在其實現(xiàn)中使用
String但不接受字符串參數(shù)也不返回字符串，則將不認為它使用String。可通過先轉(zhuǎn)到類或包，然后在導(dǎo)航欄上單擊“用法”鏈接，訪問生成的“用法”頁。
- -version
- 在生成文檔中包括 @version 文本。缺省地將省略該文本。
- -author
- 在生成文檔中包括 @author 文本。
- -splitindex
- 將索引文件按字母分割成多個文件，每個字母一個文件，再加上一個包含所有以非字母字符開頭的索引項的文件。
- -windowtitle title
- 指定放入 HTML <title> 標(biāo)記中的標(biāo)題。它將出現(xiàn)在窗口標(biāo)題欄中和為該頁創(chuàng)建的任何瀏覽器書簽（最喜歡的地方）中。該標(biāo)題不應(yīng)該包含任何 HTML 標(biāo)記，因為瀏覽器將不能正確解釋它們。在 title 中的任何內(nèi)部引號必須轉(zhuǎn)義。如果省略 -windowtitle，則 Javadoc 對該選項使用 -doctitle 的值。
- -doctitle title
- 指定放置在靠近概述概覽文件頂部的標(biāo)題。該標(biāo)題將作為一級標(biāo)題，居中地直接放在導(dǎo)航欄下面。title 可包含 html 標(biāo)記和空格，但是如果這樣，則必須用引號將它括起。在 title 中的任何內(nèi)部引號必須轉(zhuǎn)義。
- -title title
- 該選項不再存在。它僅存在于 Javadoc 1.2 的 Beta 版中。它已重命名為 -doctitle。重命名該選項是為了更清楚地表示它定義文檔標(biāo)題而不是窗口標(biāo)題。
- -header header
- 指定放置在每個輸出文件頂部的頁眉文本。該頁眉將放在上部導(dǎo)航欄的右邊。header 可包含 HTML 標(biāo)記和空格，但是如果這樣則必須用引號將它括起。在 header 中的任何內(nèi)部引號必須轉(zhuǎn)義。
- -footer footer
- 指定放置在每個輸出文件底部的腳注文本。腳本將放置在下部導(dǎo)航欄的右邊。footer 可包含 html 標(biāo)記和空格，但是如果這樣，則必須用引號將它括起。在 footer 中的任何內(nèi)部引號必須轉(zhuǎn)義。
- -bottom text
- 指定放置在每個輸出文件底部的文本。該文本將放置在頁底，位于下部導(dǎo)航欄的下面。其中 text 可包含 HTML 標(biāo)記和空格，但是如果這樣，則必須用引號將它括起。在 text 中的任何內(nèi)部引號必須轉(zhuǎn)義。
- -link docURL
- 創(chuàng)建鏈接指向已用 javadoc-生成的 外部引用類 的文檔。參數(shù) docURL是想要鏈接到的 javadoc-生成外部文檔的 URL。該位置可以是相對的或絕對的 URL。
也就是說，該選項使得可鏈接到代碼所引用但是當(dāng)前 javadoc 運行沒有產(chǎn)生其文檔的類。為保證這些鏈接指向有效頁，必須知道那些 HTML 頁所在位置，并用 docURL 指定其位置。例如，這將允許第三方文檔鏈接到
http://java.sun.com上的java.*文檔。另一種用途是用于包集之間的 交叉-鏈接： 對一個包集執(zhí)行 javadoc，然后再對另一個包集運行 javadoc，在兩個集合之間創(chuàng)建雙向鏈接。另一個用途是作為到 更新文檔 的“hack”： 在整個包集上執(zhí)行 javadoc，然后對更改過的包的較小集再次運行 javadoc，從而將更新文件插回到原集中。（這樣做可節(jié)省時間，但是需要小心使用 -- 如果從子集中添加或刪除 API，則將會丟失或破壞索引中的鏈接。）按如下使用
-link選項：
- 省略
-link選項，使 javadoc 只創(chuàng)建指向當(dāng)前運行中正在生成的文檔中 API 的鏈接。（不使用-link選項，Javadoc 將不創(chuàng)建外部引用文檔的鏈接，因為它不知道該文件是否存在（或其位置）。）- 包括
-link選項，使用 javadoc 還創(chuàng)建指向位于 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。并且以如下內(nèi)容開始：java.applet java.awt java.awt.color java.awt.datatransfer java.awt.dnd java.awt.event java.awt.font 等等。當(dāng) javadoc 不帶
-link選項運行時，在它生成文檔時，當(dāng)它遇到屬于 外部引用類 的名字時，它將打印不帶鏈接的名字。但是，如使用-link選項，則 Javadoc 將在指定 docURL 的package-list文件中搜索該包名。如果它查找到該包名，則將 URL 添加到該名字前面。（如果 URL 是相對路徑并且 -d 目的目錄選項是相對路徑，則 Javadoc 將目的目錄的相對路徑添加到 URL 中，以使鏈接在目的目錄中可用。）為了不產(chǎn)生無效鏈接，外部引用的所有文檔都必須在指定 URL 存在。Javadoc 將不會檢查這些頁的存在 -- 它只檢查 package-list 的存在。
如果 javadoc 的參數(shù)是源文件而不是包，則將創(chuàng)建 package-list, 文件但是為空。
示例 - 例如，下面命令導(dǎo)致 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 -linkdocURL1-linkdocURL2... -linkdocURLncom.mypackage其中 docURL1、 docURL2、 ... docURLn 分別指向外部文檔的根目錄，各自包含一個
package-list文件。交叉鏈接 - 注意在交叉鏈接兩個或多個還沒有生成的文檔時，可能需要“啟動”。也就是說，如果任何文檔的
package-list都不存在，則在對第一個文檔運行 javadoc 時，第二個文檔的包列表文件也將不存在。因而，要創(chuàng)建外部鏈接，必須在生成第二個文檔之后重新生成第一個文檔。在這種情況中，第一次生成文檔的目的是創(chuàng)建其包列表（如果能確定包名，也可手工創(chuàng)建包列表）。然后生成帶外部鏈接的第二個文檔。Javadoc 在需要的外部
package-list文件不存在時打印警告信息。更新文檔 -
-link選項的第三個用途是如果項目有數(shù)十個或數(shù)百個包，并且已對整個目錄樹運行了 javadoc，現(xiàn)在，在單獨的運行中，想要快速地進行一些小的修改，并對源目錄樹的一小部分重新運行 javadoc，這時它是非常有用的。這有些類似于 hack，因為它只在改變文檔注釋時才能正常工作，而修改簽名則不行。如果想要在源代碼中添加、刪除或改變?nèi)魏魏灻?，則可能在索引、包目錄樹、繼承成員列表、用法頁或其他位置出現(xiàn)無效鏈接。首先，為這次小運行新建一個目的目錄，并將
-link和-d設(shè)置成相同的相對路徑： 如果原文檔位于目錄html中，則為：C:> javadoc -d update -linkoffline . html com.mypackage當(dāng) javadoc 完成后，復(fù)制
update中生成的文件并覆蓋html中的原文件。背景知識： 一般地，在 javadoc 運行時，它有可能為其生成頁中出現(xiàn)的名字產(chǎn)生鏈接： 例如在簽名、
@see標(biāo)記、{@link}標(biāo)記、概覽、層次、概述和索引中。有些鏈接將轉(zhuǎn)到當(dāng)前運行中生成的頁，而其他鏈接有可能轉(zhuǎn)到不是在當(dāng)前運行中生成的頁。
- -linkoffline docURL packagelistURL
- 該選項為外部引用類名字創(chuàng)建指向文檔的鏈接，其中：
- docURL 是想要鏈接到的 javadoc 生成的外部文檔的根目錄的 URL。該位置可以是相對的或絕對的 URL。
- packagelistURL 是包含文檔的包列表文件所在目錄的 URL。（如果需要，可手工創(chuàng)建該文件。）
該選項是
-link的一種變體。如果在運行 javadoc 時包列表文件在 docURL 位置不存在，則可使用-linkoffline。如果知道文檔鏈接到的包名和文檔所在位置，則可以在該包列表文件實際存在于該位置之前，生成帶外部鏈接的文檔。這使得可用自己的包列表副本，生成具有適當(dāng)鏈接的文檔。當(dāng)需要生成鏈接指向包名已知但尚未發(fā)布的新外部文檔（但是還沒有建立）時，這時非常有用的。這使得兩個公司可同時發(fā)布他們的文檔。它還允許生成鏈接到?jīng)]有包列表文件的外部文檔（或許它是用 Javadoc 1.0、1.1 或最高 1.2 Beta3 生成）的文檔。
注意該選項在運行 javadoc 時不需要訪問文檔 URL。因而，即使該 URL 位于 WWW 上，在生成文檔時也不需要 web 鏈接。
如下所示，要使用該選項，請指定 docURL1（javadoc 生成的外部引用類的文檔的位置）和 packagelistURL1（其包列表文件的位置）。如果它們具有相同位置，則可僅使用
-link選項。對每個想要引用的生成文檔，需要包括-linkoffline一次：
C:>javadoc -linkofflinedocURL1packagelistURL1-linkofflinedocURL2packagelistURL2例如，下面的命令使用第一個參數(shù)給定的 URL 添加鏈接，并在第二個參數(shù)給定的路徑中查找
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選項指定每個組。各組按命令行中指定的次序出現(xiàn)在頁面上，組內(nèi)的包按字母排序。對于給定-group選項，與 packagepattern 表達式列表匹配的包出現(xiàn)在標(biāo)題為 groupheading 的表格中。
- groupheading 可以為任何文本，并可包括空格。該文本將放置在該組的表格標(biāo)題中。
- packagepattern 可以為任何包名，也可以為任何包名的開頭后跟星號（
*）。星號是通配符，表示“匹配任何字符”。它是唯一允許的通配符。一組中可包包括多個模式，并用分號（;）分隔它們。注意： 如果在模式或模式列表中使用星號，則模式 列表必須位于引號內(nèi)部，例如
"java.lang*:java.util"
如果沒有提供任何
-group選項，則所有包都將放在一組中，并且其標(biāo)題為“包”。如果所有組未包括全部帶文檔包，則剩余的任何包將出現(xiàn)在一個單獨的組中，且其標(biāo)題為“其他包”。例如，下面的選項將四個帶文檔包分成“核心包”、“擴展包”和“其他包”。注意后面的“點”號不出現(xiàn)在 "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結(jié)果分組為：
- 核心包
java.langjava.lang.reflectjava.util- 擴展包
javax.servlet- 其他包
java.new
-nonavbar 選項是非常有用的。
help-doc.html，它在 Javadoc 中硬編碼。該選項使得可覆蓋這種缺省情況。其中 filename 可以是任何名字，不局限于 help-doc.html -- Javadoc 將相應(yīng)調(diào)整導(dǎo)航欄中的鏈接。例如：
C:> javadoc -helpfile C:\user\myhelp.html java.awt
stylesheet.css，它在 Javadoc 中硬編碼。該選項使得可覆蓋這種缺省情況。其中 filename 可以是任何名字，不局限于 stylesheet.css。例如：
C:> javadoc -stylesheetfile C:\user\mystylesheet.css com.mypackage
可以對整個包或單個類運行 javadoc。每個包名有一個相應(yīng)的目錄名。在下面的示例中，源文件位于
C:\home\src\java\awt\*java。目的目錄是C:\home\html。建立包的文檔
要建立包的文檔，該包的源文件（
*.java）必須位于一個與該包名字相同的目錄中。如果包名由幾個標(biāo)識符組成（用點號分隔），則每個標(biāo)識符代表一個不同的目錄。因而，所有java.awt類必須位于名為java\awt\的目錄中?？捎萌缦聝煞N方式之一運行 javadoc -- 通過改變目錄（用cd）或使用sourcepath選項。不能使用通配符指定多個包。
- 情況 1- 換到包目錄 - 換到全限定包的父目錄。然后運行 run javadoc，并提供想要建立其文檔的一個或多個包的名字：
C:> cd C:\home\src\ C:> javadoc -d C:\home\html java.awt java.awt.event- 情況 2 - 從任何目錄 - 在這種情況下，當(dāng)前目錄是什么沒有關(guān)系。運行 javadoc 時用
sourcepath提供全限定包的父目錄，并提供想要建立其文檔的一個或多個包的名字：C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt java.awt.event這兩種情況都將產(chǎn)生包
java.awt和java.awt.event中公共和保護類和接口的 HTML 格式文檔，并將 HTML 文件保存在指定目的目錄（C:\home\html）中。因為要生成兩個或多個包，所以文檔具有三個框架 -- 包列表、類列表和主頁。建立類的文檔
要建立一個或多個源文件（
.java）的文檔，這些文件不必位于特定目錄中?？梢杂萌缦聝煞N方式之一運行 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該示例產(chǎn)生類
Button、Canvas和以Graphics開頭的類的 HTML 格式文檔。因為是源文件而不是包名作為參數(shù)傳遞給 javadoc，所以文檔具有兩個框架 -- 類列表和主頁。- 情況 2 - 改變到包的根目錄 - 當(dāng)要為相同根目錄下不同子包中的單個源文件建立文檔時，這是非常有用的。改變到包的根目錄，并提供源文件相對于其根的路徑。
C:> cd /home/src/ C:> javadoc -d /home/html java/awt/Button.java java/applet/Applet.java該示例產(chǎn)生類
Button和Applet的 HTML 格式文檔。- 情況 3 - 從任何目錄 - 在這種情況下，當(dāng)前目錄是什么沒有關(guān)系。運行 javadoc，并提供想要建立其文檔的
.java文件的絕對路徑（或相對于當(dāng)前目錄的相對路徑）。C:> javadoc -d C:\home\html C:\home\src\java\awt\Button.java C:\home\src\java\awt\Graphics*.java該示例產(chǎn)生類
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) \ /* 添加窗口標(biāo)題 */ -doctitle $(DOCTITLE) \ /* 添加文檔標(biāo)題 */ -header $(HEADER) \ /* 添加運行頁眉文本 */ -bottom $(BOTTOM) \ /* 添加底部文本 */ -group $(GROUPCORE) \ /* 概述頁的核心標(biāo)題 */ -group $(GROUPEXT) \ /* 概述頁的擴展標(biāo)題 */ -overview overview-core.html \ /* 概述文本 */ -J-Xmx180m \ /* 180MB 內(nèi)存 */ java.lang java.lang.reflect \ /* 要建立其文檔的包 */ java.util java.io java.net java.applet WINDOWTITLE = ‘Java 平臺 1.2 最終 API 規(guī)范‘ DOCTITLE = ‘Java<sup><font size="-2">TM</font></sup> Platform 1.2 Final API Specification‘ HEADER = ‘<b>Java Platform 1.2</b><br><font size="-1">Final</font>‘ BOTTOM = ‘<font size="-1"><a > 提交 bug 或功能 </a><br><br>Java 是 Sun Microsystems , Inc 在美國和其他國家 的商標(biāo)或注冊商標(biāo)。<br>Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road,<br>Palo Alto, California, 94303, U.S.A. 保留所有權(quán)利。</font>‘ GROUPCORE = ‘"核心包" "java.*:com.sun.java.*:org.omg.*" GROUPEXT = ‘"擴展包" "javax.*"‘如果省略
-windowtitle選項，則 javadoc 將文檔標(biāo)題復(fù)制到窗口標(biāo)題。-windowtitle選項是沒有必要的，除非文檔標(biāo)題包含 HTML 標(biāo)記。如果像這里所做的一樣省略
-footer選項，則 javadoc 將頁眉文本復(fù)制到腳注文本。其他重要的選項是 -classpath 和 -link。
CLASSPATH- 提供 javadoc 用于查找用戶類文件路徑的環(huán)境變量。該環(huán)境變量將被
-classpath選項覆蓋。用分號分隔目錄，例如：- .;C:\classes;C:\home\java\classes
如有意見，請發(fā)送到： javadoc-tool@sun.com
