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