javadoc - Java API 文档生成器（Windows版本）
文章目錄
- 簡介
- 命令語法結構
- Javadoc Doclets
- 術語
- 帶文檔的類
- 引用類
- 外部引用類
- 源文件
- 源代碼文件
- 包注釋文件
- 概述注釋文件
- 其他未處理文件
- 生成的文件
- 基本內容頁
- 交叉參考頁
- 支持文件
- HTML 框架
- 生成的文件結構
- 文檔注釋
- 注釋源代碼
- JAVADOC 標記
- @author name-text
- @deprecated deprecated-text
- @exception class-name description
- {@link name label}
- @param parameter-name description
- @return description
- @see reference
- @see "string"
- @see label
- @see package.class#member label
- @since since-text
- @serial field-description
- @serialField field-name field-type field-description
- @serialData data-description
- @throws class-name description
- @version version-text
- 可使用標記的地方
- 概述文檔標記
- 包文檔標記
- 類和接口文檔標記
- 域文檔標記
- 構造函數和方法文檔標記
- 命令行參數文件
- Javadoc 選項
- -overview path\filename
- -public
- -protected
- -package
- -private
- -help
- -doclet class
- -docletpath classpathlist
- -1.1
- -sourcepath sourcepathlist
- -classpath classpathlist
- -bootclasspath classpathlist
- -extdirs dirlist
- -verbose
- -locale language_country_variant
- -encoding name
- -Jflag
- 標準 Doclet 提供的選項
- -d directory
- -use
- -version
- -author
- -splitindex
- -windowtitle title
- -doctitle title
- -title title
- -header header
- -footer footer
- -bottom text
- -link docURL
- -linkoffline docURL packagelistURL
- -group groupheading packagepattern:packagepattern:...
- -nodeprecated
- -nodeprecatedlist
- -notree
- -noindex
- -nohelp
- -nonavbar
- -helpfile path\filename
- -stylesheetfile path\filename
- -docencoding name
- 簡單示例
- 建立包的文檔
- 建立類的文檔
- 建立包和類的文檔
- 實際示例
- 環境
- 另請參閱
簡介
javadoc 是 Sun 公司提供的一個技術，JDK 的 bin 目錄下你可以看到命令執行文件 javadoc，它從程序源代碼中抽取注釋內容，形成一個和源代碼配套的 API 幫助文檔。也就是說，只要在編寫程序時以一套特定的標簽作注釋，在程序編寫完成后，通過 Javadoc 就可以同時形成程序的開發文檔了。
javadoc 命令只能提取源代碼文件中的文檔注釋標記 /**...*/ 內的內容。文檔注釋內可以包含普通文本，HTML 標記和 JavaDoc 標記，這些內容構成 JavaDoc 文檔。
在實現時，javadoc 依賴于 java 編譯器完成其工作。javadoc 會調用 javac 編譯類、方法、變量的聲明部分，而忽略它們的實現部分。javadoc 會建立類的內容豐富的內部表示，包括類層次和“使用”關系，并讀取源文件中文檔注釋的內容，解析注釋中的注解，最后生成 HTML 格式的說明文檔。
實際上，javadoc 將在不帶方法體的純 stub 文件的 .java 源文件上運行。這意味著可以創建 API 的最早期版本，在編寫任何代碼之前，就可編寫文檔注釋并運行 javadoc。
依賴編譯器可以確保 HTML 輸出完全對應于實際實現，這些實現可能有賴于隱式的（而非顯式的）源代碼。例如，javadoc 將建立在 .class 文件中存在但在源代碼中不存在的缺省構造方法（Java 語言規范的第 8.6.7 節）的文檔。
當 javadoc 建立其內部文檔結構時，它將加載所有引用的類。由于這一點，javadoc 必須能查找到所有引用的類，包括引導類、擴展類和用戶類。有關詳細信息，參見如何查找類。一般而言，所創建的類必須加載為擴展或位于 javadoc 的類路徑中。
命令語法結構
命令的語法格式：
javadoc [option] [packagenames] [sourcefiles][@fileName]
option：命令選項
packagenames：一系列包的名字，包與包之間用空格隔開，例如：java.lang java.lang.reflect java.awt。必須分別指定想要為之建立文檔的每個包，javadoc 不會遞歸處理子包，另外也不支持使用通配符。
sourcefiles：一系列源文件名，使用空格分隔。可以混合包名和源文件名，例如：java.awt /home/src/java/awt/Graphics*.java java.lang.String。
@fileName：當需要指定的文件太多時，可以使用 @fileName 來簡化，fileName 是一個文件名，該文件需要在當前工作目錄下，文件中輸入源文件的路徑，路徑之間可以使用空格分隔或者換行分隔。當然你也可以在文件中指定多個包路徑，同樣路徑之間可以使用空格分隔或者換行分隔
Javadoc Doclets
可使用 doclets 自定義 Javadoc 輸出的內容和格式。Javadoc 具有一個缺省的“內嵌”doclet，叫作標準 doclet，它生成 HTML-格式的 API 文檔。用戶可修改或擴展標準 doclet，或編寫自己的 doclet 以生成 HTML、XML、MIF、RTF 或想要的任何輸出格式。
當沒有用 -doclet 命令行選項指定自定義 doclet 時，Javadoc 將使用缺省的標準 doclet。不管使用哪個 doclet，javadoc 工具都有幾個命令行選項可用。標準 doclet 還添加了額外的命令行選項集。
術語
帶文檔的類
在 javadoc 運行期間為之生成了全部文檔的類和接口。要生成文檔，源文件必須可用，并且其源文件名或包名必須傳遞到 javadoc 命令中。
引用類
在帶文檔的類和接口的定義（實現）中顯式引用的類和接口。引用的例子包括返回類型、參數類型、強制轉換類型、已實現接口、導入類，等等。在文檔注釋（例如 @see 標記）中引用的類不算作引用類。當 Javadoc 運行時，它將 javadoc 引導類路徑和類路徑中所有的引用類加載到內存中（對于沒有找到的引用類，Javadoc 將顯示“類未找到”警告信息）。 Javadoc 可從類文件中獲得足夠的信息，以確定其存在性及其成員的全限定名字。
外部引用類
在 javadoc 運行期間沒有生成其文檔的引用類。也就是說，這些類對于該次 javadoc 運行是外部的。文檔中名字到這些類的鏈接稱為外部引用或外部鏈接。例如，如果僅對 java.awt 包運行 javadoc，則 java.lang 中的任何類（如 Object）都是外部引用類。可使用 -link 選項鏈接外部引用類。
源文件
javadoc 將根據四種不同的“源”文件生成輸出： Java 語言源文件（.java）、包注釋文件、概述注釋文件和其他未處理文件。下面介紹了后三種類型。
源代碼文件
略
包注釋文件
每個包具有它自己的文檔注釋，保存在其自己的“源”文件中，Javadoc 將把它合并到生成的包概覽頁中。通常可在這個注釋中包括適用于整個包的任何文檔。
要創建包注釋文件，必須將它命名為 package.html 并將它與 .java 文件一起放在源樹中的包目錄中。Javadoc 將自動在該位置查找該文件名。注意該文件名對于所有包都是相同的。
包注釋文件的內容是一個大文檔注釋，用 HTML 編寫，像所有其他注釋一樣，但有一個例外：文檔注釋不應該包括注釋分隔符 /** 和 */ 或前導星號。在編寫注釋時，第一句應該是關于包的概覽，并且在 <body> 和第一句之間不應該插入任何標題或其他文本。可包括 package 標記；與所有文檔注釋一樣，除了 {@link} 之外的所有標記都應該位于描述之后。如果添加 @see 標記，則它必須是全限定名字。
當 Javadoc 運行時，它將自動查找該文件；如果找到，則 Javadoc 做下列事情：
1.復制 和 標記之間的全部內容以進行處理。
2.處理存在的任何包標記。
3.在它生成的包概覽頁底部插入處理后的文本，例如，包概覽。
4.將包注釋的第一句復制到包概覽頁和概述頁（例如概述概覽）的頂部。
概述注釋文件
每個要為之建立文檔的應用程序或包集可以有它自己的概述文檔注釋，保存在其自己的“源”文件中，Javadoc 將把它合并到生成的概述頁中。在該注釋中通常可包括適用于整個應用程序或包集的任何文檔。
要創建概述注釋文件，可將該文件命名為想要的任何名字（通常為 overview.html）并將它放置在任何地方（通常位于源樹的最頂層中）。注意對于相同源文件集可有多個概述注釋文件，以用于對不同包集多次運行 javadoc。例如，如果 java.applet 包的源文件包含在 C:\user\src\java\applet 目錄中，則可創建概述注釋文件 C:\user\src\overview.html。
概述注釋文件的內容是一個大文檔注釋，用 HTML 編寫，與前面介紹的包注釋文件類似。在編寫注釋時，第一句應該是關于應用程序或包集的概覽，并且在 和第一句之間不要插入標題或任何其他文本。可包括概述標記；與所有文檔注釋一樣，除了 {@link} 之外的所有標記都就位于描述之后。如果添加 @see 標記，則它必須是全限定名字。
當運行 Javadoc 時，可用 -overview 選項指定概述注釋文件。然后將以與包注釋文件類似的方法處理該文件。
1.復制 <body> 和 </body> 標記之間的全部內容以進行處理。
2.處理存在任何 概述標記。
3.將處理過后的文本插入到生成的概述頁（例如 概述概覽）的底部。
4.將概述注釋的第一句復制到概述概覽頁的頂部。
其他未處理文件
還可在源文件中包括想要 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"> */生成的文件
缺省地，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 命令中時，它將僅在左邊欄中創建一個框架 – 類列表。當給 javadoc 傳遞兩個或多個包名時，它將創建第三個框架（列出所有包）以及一個概述頁（Detail）。可通過在“無框架”鏈接上單擊或在 overview-summary.html 進入，繞過框架。
如果您不熟悉 HTML 框架，則應該記住框架可具有焦點，以進行打印或滾動。要使框架具有焦點，可在其上單擊。然后在許多瀏覽器中，箭頭鍵和翻頁鍵將滾動該框架，而打印菜單命令將打印它。
根據是否想要 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 接口用法頁文檔注釋
注釋源代碼
可以在源代碼中任何實體（類、接口、方法、構造函數或域）聲明的前面包括文檔注釋。它們也稱為 Javadoc 注釋，并且文件必須用 HTML 編寫，它們應使用 HTML 實體并可使用 HTML 標記。用戶可使用自己瀏覽器支持的任何 HTML 版本；我們編寫的標準 doclet 可在其它地方（文檔注釋外部）生成 HTML 3.2-兼容代碼，其中包括級聯樣式表單和框架（由于使用框架集，我們在每個生成文件前面添加了“HTML 4.0”）。
例如，小于 (<) 和大于 (>) 符號的實體應該寫為 < 和 >。類似地，與符號（&）應該寫為 &。在下面的示例中顯示了粗體 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 章“文檔注釋”。
JAVADOC 標記
Javadoc 解析 Java 文檔注釋中嵌入的特殊標記。這些文檔標記可幫助自動從源代碼生成完整的格式化 API。標記用“at”符號（@）開頭，并區分大小寫 – 必須按照正確大小寫字母輸入它們。標記必須從一行的開頭開始（位于任何前導空格和可選星號之后），否則它將被視為普通文本。按規定應將相同名字的標記放在一起。例如，將所有 @see 標記放在一起。
有關我們將在未來版本中引入的標記的信息，參見 提議標記。
當前標記有：
標記 引入該標記的 JDK 版本 @author 1.0 @deprecated 1.0 @exception 1.0 {@link} 1.2 @param 1.0 @return 1.0 @see 1.0 @serial 1.2 @serialData 1.2 @serialField 1.2 @since 1.1 @throws 1.2 @version 1.0@author name-text
當使用 -author 選項時，用指定的 name-text 在生成文檔中添加“Author”項。文檔注釋可包含多個 @author 標記。可以對每個 @author 指定一個或多個名字。在前一種情況中，Javadoc 將在名字之間插入逗號（,）和空格。在后一種情況下，將全部文本復制到生成文檔中而不進行解析。如果想要用逗號以外的本地化名字分隔符，則應每行使用這個名字。
@deprecated deprecated-text
添加注釋，指示不應再使用該 API（盡管它仍可用）。Javadoc 將 deprecated-text 移動到描述前面，用斜體顯示，并在它前面添加粗體警告： “不鼓勵使用”。
deprecated-text 的首句至少應該告訴用戶什么時候開始不鼓勵使用該 API 及使用什么替代它。Javadoc 僅將首句復制到概覽部分和索引中。后面的語句還可解釋為什么不鼓勵使用它。還應包括一個指向替代 API 的 {@link} 標記（對于 Javadoc 1.2 或更新版本）：
對于 Javadoc 1.2，使用 {@link} 標記。這將在需要的地方創建內嵌鏈接。例如：
/** * @deprecated 在 JDK 1.1 中，被 {@link #setBounds(int,int,int,int)} 取代。 */對于 Javadoc 1.1，標準格式是為每個 @deprecated 標記創建 @see 標記（它不能內嵌）。
有關不鼓勵使用的信息，參見 @deprecated 標記。
@exception class-name description
@exception 標記是 @throws 的同義標記。
{@link name label}
插入指向指定 name 的內嵌鏈接。該標記中 name 和 label 的語法與 @see 標記完全相同，如下所述，但是它產生內嵌鏈接而不是在“參見”部分中放置鏈接。該標記用花括號開始并用花括號結束，以使它區別于其他內嵌文本。如果在標簽內需要使用“}”，則請使用 HTML 實體表示法 }
對于一個語句中所允許的 {@link} 標記數目沒有限制。可以在文檔注釋的描述部分或任何標記（例如 @deprecated、@return 或 @param）的文本部分中使用該標記。
例如，下面是一個引用 getComponentAt(int, int) 方法的注釋：
/** * 使用 {@link #getComponentAt(int, int) getComponentAt} 方法。 */根據它，標準 doclet 將生成如下 HTML（假定它引用相同包中另一個類）：
使用 <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 通過查找第一個字符為雙引號（"）的情形來區分它與前面的情況。例如：
這將生成如下文本：
參見：
“Java 編程語言”
@see label
添加 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 是可選的；如果省略，則名字將作為可見文本出現，而且嵌入在 HTML 標記中。當想要縮寫可見文本或不同于名字的可見文本時，可使用 label。
package.class#member 是 Java 語言中的任何有效名字 – 包名、類名、接口名、構造函數名、方法名或域名 – 除了用 hash 字符（#）取代成員名前面的點之外。如果該名字位于帶文檔的類中，則 Javadoc 將自動創建到它的鏈接。要創建到外部引用類的鏈接，可使用 -link 選項。使用另兩種 @see 形式的任何一種引用不屬于引用類的名字的文檔。第一個參數將在 指定名字 中詳細介紹。
label 是可選文本，它是鏈接的可見標簽。label 可包含空格。如果省略 label，則將顯示 package.class.member，并相對于當前類和包適當縮短。-- 參見 如何顯示名字。
空格是 package.class#member 和 label 之間的分界符。括號內的空格不表示標簽的開始，因此在方法各參數之間可使用空格。
示例 - 在該示例中，Character 類中的 @see 標記引用 String 類中的 equals 方法。該標記包括兩個參數： 名字“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 可以為方法或構造函數。
下述說明適用于上表：
第一套形式（沒有類和包）將導致 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 的父類。 在步驟 4 和 5 中，Javadoc 不按任何指定的次序（該次序取決于特定編譯器）搜索包中的類或接口。在步驟 5 中，Javadoc 將在 in java.lang 中查找，因為它是由所有程序自動導入的。
Javadoc 沒有必要在子類中查找，也沒有必要在其他包中查找，即使它們的文檔在同一次運行中生成。例如，如果 @see 標記位于 java.awt.event.KeyEvent 類中并引用 java.awt 包中的名字，則 javadoc 將不查找該包，除非該類導入它。
如何顯示名字 - 如果省略 label，則將顯示 package.class.member。一般地，將相對于當前類和包適當縮短它。這里“縮短”是指僅顯示必要的名字，使之盡可能短。例如：
@see 示例
右邊的注釋顯示了當 @see 標記位于其他包（例如 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 規范 @see "The Java Programming Language" // "Java 編程語言"@since since-text
用 since-text 指定的內容給生成文檔添加“Since”標題。該文本沒有特殊內部結構。該標記表示該改變或功能自 since-text 所指定的軟件版本之后就存在了。例如：@since JDK1.1
@serial field-description
用于缺省可序列化域的文檔注釋中。
可選的 field-description 增強了文檔注釋對域的描述能力。該組合描述必須解釋該域的意義并列出可接受值。如需要，該描述可有多行。
應該對自 Serializable 類的最初版本之后添加的每個可序列化域添加 @since 標記。
要獲得私有類的序列化形式，可使用 -private 選項。因而，要生成所有公共類和私有類的序列化形式，可用 -private 選項運行 javadoc。
有關如何使用這些標記的信息，以及相應示例，參見 Java 對象序列化規范 中第 1.6 節“建立類的可序列化域和數據的文檔。
@serialField field-name field-type field-description
Documents an ObjectStreamField component of a Serializable class’s serialPersistentFields member. One @serialField tag should be used for each ObjectStreamField component.
@serialData data-description
data-description 以序列化形式記錄數據的類型和順序。尤其是 writeObject 方法所寫入的可選數據和 Externalizable.writeExternal 方法寫入的全部數據。
@serialData 標記可用于 writeObject, readObject, writeExternal, readExternal, writeReplace, and readResolve 等方法的文檔注釋中。
@throws class-name description
@throws 和 @exception 標記同義。用 class-name 和 description 文本給生成的文檔添加“拋出”子標題。其中 class-name 是該方法可拋出的異常名。如果該類不是全限定的，則 Javadoc 使用 搜索次序 查找該類。
@version version-text
當使用 -version 選項時用 version-text 指定的內容給生成文檔添加“版本”子標題。該文本沒有特殊內部結構。文檔注釋最多只能包含一個 @version 標記。版本通常是指包含該類或成員的軟件（例如 JDK）版本。
可使用標記的地方
下面介紹在哪些地方可使用標記。注意這四個標記可用于所有文檔注釋中：@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) {
…
}
命令行參數文件
為了縮短或簡化 javadoc 命令，可指定一個或多個其中每行包含一個源文件名或包名的文件。在命令行中，采用 ‘@‘ 字符加上文件名的方法將它指定為文件列表。當 javadoc 遇到用字符‘@’開頭的參數時，它將操作該文件中的名字，仿佛這些名字位于命令行上一樣。
例如，可以在名為 packages 的文件中列出所有包名。該文件可能形如：
com.mypackage1 com.mypackage2 com.mypackage3然后可用如下命令運行 javadoc：
C:> javadoc -d apidocs @packagesJavadoc 選項
javadoc 工具使用 doclets 確定其輸出。除非使用 -doclet 選項指定自定義 doclet ，否則 Javadoc 使用缺省的標準 doclet。Javadoc 提供一套命令行選項，可用于任何 doclet – 這些選項將在下面的子標題 Javadoc 選項 中介紹。標準 doclet 提供了一套額外的命令行選項，它們將在下面的子標題–標準 Doclet 提供的選項中介紹。所有選項名都不區分大小寫，但是其參數可能區分大小寫。
選項包括：
-1.1 -author -bootclasspath -bottom -classpath -d -docencoding -doclet -docletpath -doctitle -encoding -extdirs -footer -group -header -help -helpfile -J -link -linkoffline -locale -nodeprecated -nodeprecatedlist -nohelp -noindex -nonavbar -notree -overview -package -private -protected -public -sourcepath -splitindex -stylesheetfile -title -use -verbose -version -windowtitle-overview path\filename
指定 javadoc 應該從 path\filename 所指定的“源”文件中獲取概述文檔，并將它放到概述頁中（overview-summary.html）。其中 path\filename 是相對于 -sourcepath 的相對路徑名。
盡管可對 filename 使用任何名字并將它放在 path 指定的任何地方，但是通常將它命令為 overview.html 并將它放入包含最頂級包目錄的源目錄樹中。在該位置，建立包文檔時不需要 path，因為 -sourcepath 將指向該文件。例如，如果 java.lang 包的源目錄樹是 /src/classes/java/lang/，則可以概述文件放到 /src/classes/overview.html。參見 實際示例。
有關 path\filename 指定文件的信息，參見 概述注釋文件。
在一定情況下，將不產生概述頁。有關詳細信息，參見 HTML 框架。
-public
只顯示公有類及成員。
-protected
只顯示受保護的和公有的類及成員。這是缺省狀態。
-package
只顯示包、受保護的和公有的類及成員。
-private
顯示所有類和成員。
-help
顯示聯機幫助，它將列出這些 javadoc 和 doclet 命令行選項。
-doclet class
指定啟動用于生成文檔的 doclet 的類文件。該 doclet 定義了輸出的內容和格式。如果未使用 -doclet 選項，則 javadoc 使用標準 doclet 生成缺省 HTML 格式。該類必須包含 start(Root) 方法。該啟動類的路徑由 -docletpath 選項定義。
-docletpath classpathlist
指定 doclet 類文件的路徑，該類文件用 -doclet 選項指定。如果 doclet 已位于搜索路徑中，則沒有必要使用該選項。
-1.1
生成具有用 Javadoc 1.1 生成的文檔的外觀和功能的文檔。也就是說，頁的背景為灰色，用圖像做頁眉，使用 bullet 列表而不是表格，具有單級目的目錄結構，不包含繼承 API，不使用 HTML 框架，并且不支持內部類。該選項還將索引分割成每個字母一個文件。如果想要這種外觀，則該選項比 javadoc 1.1 優越之處在于修正了一些錯誤。
不是所有選項都能用于 -1.1 選項。為了查看哪些選項可用，可執行：
C:> javadoc -1.1 -help在該列表中顯示的 -footer 選項在功能上與本頁中其他地方介紹的 -bottom 選項相同。而 -title 選項在功能上與 -doctitle 相同。
-sourcepath sourcepathlist
當將包名傳遞到 javadoc 命令中時，指定查找源文件（.java）的搜索路徑。注意只有當用 javadoc 命令指定包名時才能使用 sourcepath 選項 – 它將不會定位傳遞到 javadoc 命令中的 .java 文件。如果省略 -sourcepath，則 javadoc 使用類路徑查找源文件（參見 -classpath）。
將 sourcepathlist 設置成正在生成其文檔的包的源樹的根目錄。例如，假定想要為叫作 com.mypackage 的包建立文檔，其源文件位于：
C:\user\src\com\mypackage\*.java
在這種情況下，將把 sourcepath 指定為 C:\user\src，該目錄包含 com\mypackage，然后提供包名 com.mypackage：
javadoc -sourcepath C:\user\src com.mypackage這是相當容易記憶的，注意如果將源路徑和包名級聯到一起，并將點號改為斜杠“/”，則最后將得到該包的完整路徑：C:\user\src\com\mypackage.
-classpath classpathlist
指定 javadoc 將在其中查找引用類的路徑 – 引用類是指帶文檔的類加上它們引用的任何類。Javadoc 將搜索指定路徑的所有子目錄。classpathlist 可以包含多個路徑，它們用分號分隔。有關如何指定 classpathlist，請遵循類路徑文檔中的指令。
如果省略 -sourcepath，則 Javadoc 使用 -classpath 查找源文件和類文件（為了向后兼容性）。因而，如果想要在不同的路徑中搜索源文件和類文件，則應使用 -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 環境變量（如果它已設置）。如果二者都未設置，則 Javadoc`將從當前目錄中搜索類。
有關 Javadoc 如何使用 -classpath 查找用戶類及相關擴展類和自舉類的深入介紹，參見 如何查找類。
-bootclasspath classpathlist
指定自舉類所在路徑。它們名義上是 Java 平臺類。這個 bootclasspath 是 Javadoc 將用來查找源文件和類文件（.class文件）的搜索路徑的一部分。有關詳細信息，參見 如何查找類。在 classpathlist 中用分號（;）分隔目錄。
-extdirs dirlist
指定擴展類所在的目錄。它們是任何使用 Java 擴展機制的類。這個 extdirs 是 Javadoc 將用來查找源文件和在文件的搜索路徑的一部分。有關詳細信息，參見上面的 -classpath。在 dirlist 中用分號（;）分隔目錄。
-verbose
在 javadoc 運行時提供更詳細的信息。不使用 verbose 選項時，將顯示加載源文件、生成文檔（每個源文件一條信息）和排序的信息。verbose 選項導致打印額外的信息，指定解析每個 java 源文件的毫秒數。
-locale language_country_variant
指定 javadoc 在生成文檔時使用的環境。該參數為環境名，如 java.util.Locale 文檔中所述，例如 en_US（英語，美國）或 en_US_WIN（Windows 變量）。
指定環境將導致 javadoc 為各種信息（導航欄中的字符串、列表和表格的標題、幫助文件內容、stylesheet.css 中的注釋，等等）選擇使用該環境的資源文件。它還指定按字母次序排序列表的排序次序，以及用于確定第一句結束的語句分隔符。它不決定帶文檔類的源文件中指定的文檔注釋文本的環境。
-encoding name
指定源文件編碼名，例如：EUCJIS/SJIS。如果未指定該選項，則使用平臺缺省轉換器。
-Jflag
將 flag 直接傳遞給運行 javadoc 的運行時系統 java。注意在 J 和 flag 之間不能有空格。例如，如果需要確保系統分配 32 兆內存用于處理生成文檔，則應按如下使用該標志：
C:> javadoc -J-Xmx32m -J-Xms32m com.mypackage標準 Doclet 提供的選項
-d directory
指定 javadoc 保存生成的 HTML 文件的目的目錄。(“d” 表示 “destination”) 省略該選項將導致把文件保存到當前目錄中。其中 directory 可以是絕對路徑或相對當前工作目錄的相對路徑。例如，下列代碼將生成 com.mypackage 包的文檔并將結果保存在 C:\user\doc\ 目錄中：
C:> javadoc -d \user\doc com.mypackage-use
對每個帶文檔類和包包括一個“用法”頁。該頁描述使用給定類或包的任何 API 的包、類、方法、構造函數和域。對于給定類 C，使用類 C 的任何東西將包括 C 的子類、聲明為 C 的域、返回 C 的方法以及具有 C 類型參數的方法和構造函數。
例如，下面來看一下出現在 String 的“用法”頁上的內容。java.awt.Font 類中的 getName() 方法返回類型 String。因而，getName() 使用 String，從而可在 String 的“用法”頁上找到該方法。
注意它只產生使用 API 的文檔，而不包括實現。如果方法在其實現中使用 String 但不接受字符串參數也不返回字符串，則將不認為它使用 String。
可通過先轉到類或包，然后在導航欄上單擊“用法”鏈接，訪問生成的“用法”頁。
-version
在生成文檔中包括 @version 文本。缺省地將省略該文本。
-author
在生成文檔中包括 @author 文本。
-splitindex
將索引文件按字母分割成多個文件，每個字母一個文件，再加上一個包含所有以非字母字符開頭的索引項的文件。
-windowtitle title
指定放入 HTML 標記中的標題。它將出現在窗口標題欄中和為該頁創建的任何瀏覽器書簽（最喜歡的地方）中。該標題不應該包含任何 HTML 標記，因為瀏覽器將不能正確解釋它們。在 title 中的任何內部引號必須轉義。如果省略 -windowtitle，則 Javadoc 對該選項使用 -doctitle 的值。
-doctitle title
指定放置在靠近概述概覽文件頂部的標題。該標題將作為一級標題，居中地直接放在導航欄下面。title 可包含 html 標記和空格，但是如果這樣，則必須用引號將它括起。在 title 中的任何內部引號必須轉義。
-title title
該選項不再存在。它僅存在于 Javadoc 1.2 的 Beta 版中。它已重命名為 -doctitle。重命名該選項是為了更清楚地表示它定義文檔標題而不是窗口標題。
-header header
指定放置在每個輸出文件頂部的頁眉文本。該頁眉將放在上部導航欄的右邊。header 可包含 HTML 標記和空格，但是如果這樣則必須用引號將它括起。在 header 中的任何內部引號必須轉義。
-footer footer
指定放置在每個輸出文件底部的腳注文本。腳本將放置在下部導航欄的右邊。footer 可包含 html 標記和空格，但是如果這樣，則必須用引號將它括起。在 footer 中的任何內部引號必須轉義。
-bottom text
指定放置在每個輸出文件底部的文本。該文本將放置在頁底，位于下部導航欄的下面。其中 text 可包含 HTML 標記和空格，但是如果這樣，則必須用引號將它括起。在 text 中的任何內部引號必須轉義。
-link docURL
創建鏈接指向已用 javadoc-生成的 外部引用類 的文檔。參數 docURL是想要鏈接到的 javadoc-生成外部文檔的 URL。該位置可以是相對的或絕對的 URL。
也就是說，該選項使得可鏈接到代碼所引用但是當前 javadoc 運行沒有產生其文檔的類。為保證這些鏈接指向有效頁，必須知道那些 HTML 頁所在位置，并用 docURL 指定其位置。例如，這將允許第三方文檔鏈接到 http://java.sun.com 上的 java.* 文檔。另一種用途是用于包集之間的 交叉-鏈接： 對一個包集執行 javadoc，然后再對另一個包集運行 javadoc，在兩個集合之間創建雙向鏈接。另一個用途是作為到 更新文檔 的“hack”： 在整個包集上執行 javadoc，然后對更改過的包的較小集再次運行 javadoc，從而將更新文件插回到原集中。（這樣做可節省時間，但是需要小心使用 – 如果從子集中添加或刪除 API，則將會丟失或破壞索引中的鏈接。）
按如下使用 -link 選項：
省略 -link 選項，使 javadoc 只創建指向當前運行中正在生成的文檔中 API 的鏈接。（不使用 -link 選項，Javadoc 將不創建外部引用文檔的鏈接，因為它不知道該文件是否存在（或其位置）。）
包括 -link 選項，使用 javadoc 還創建指向位于 docURL 的 外部引用類 文檔的鏈接。
注意如果 URL 位于 WWW 上，則 javadoc 在生成文檔時必須具有 web 連接以訪問 package-list。如果不能訪問，則可使用 -linkoffline 代替。
Package List - -link 選項需要一個名為 package-list 的文件（它由 Javadoc 生成）位于用 -link 指定的 URL 中。package-list 文件是簡單的文本文件，列出在該位置有文檔的包名。在下面將介紹 Javadoc 如何使用包列表。
例如，Java 平臺 1.2 API 的包列表位于 。并且以如下內容開始：
java.applet
java.awt
java.awt.color
java.awt.datatransfer
java.awt.dnd
java.awt.event
java.awt.font
等等。
當 javadoc 不帶 -link 選項運行時，在它生成文檔時，當它遇到屬于 外部引用類 的名字時，它將打印不帶鏈接的名字。但是，如使用 -link 選項，則 Javadoc 將在指定 docURL 的 package-list 文件中搜索該包名。如果它查找到該包名，則將 URL 添加到該名字前面。（如果 URL 是相對路徑并且 -d 目的目錄選項是相對路徑，則 Javadoc 將目的目錄的相對路徑添加到 URL 中，以使鏈接在目的目錄中可用。）
為了不產生無效鏈接，外部引用的所有文檔都必須在指定 URL 存在。Javadoc 將不會檢查這些頁的存在 – 它只檢查 package-list 的存在。
如果 javadoc 的參數是源文件而不是包，則將創建 package-list, 文件但是為空。
示例 - 例如，下面命令導致 Javadoc 在給定 URL 查找 package-list 文件，讀取該文件中的包名，然后在添加指向那些外部包中 API 的鏈接時使用給定 URL：
C:> javadoc -link http://java.sun.com/products/jdk/1.2/docs/api com.mypackage多鏈接 - 可提供多個 -link 選項，鏈接到任意多個外部生成文檔。 已知 Bug - Javadoc 1.2 有一個已知 bug，它使得不能提供多個 -link 命令。在未來版本中將會修正它。
為每個要鏈接的外部文檔指定不同的鏈接選項：
C:> javadoc -link docURL1 -link docURL2 ... -link docURLn com.mypackage其中 docURL1、 docURL2、 … docURLn 分別指向外部文檔的根目錄，各自包含一個 package-list 文件。
交叉鏈接 - 注意在交叉鏈接兩個或多個還沒有生成的文檔時，可能需要“啟動”。也就是說，如果任何文檔的 package-list 都不存在，則在對第一個文檔運行 javadoc 時，第二個文檔的包列表文件也將不存在。因而，要創建外部鏈接，必須在生成第二個文檔之后重新生成第一個文檔。
在這種情況中，第一次生成文檔的目的是創建其包列表（如果能確定包名，也可手工創建包列表）。然后生成帶外部鏈接的第二個文檔。Javadoc 在需要的外部 package-list 文件不存在時打印警告信息。
更新文檔 - -link 選項的第三個用途是如果項目有數十個或數百個包，并且已對整個目錄樹運行了 javadoc，現在，在單獨的運行中，想要快速地進行一些小的修改，并對源目錄樹的一小部分重新運行 javadoc，這時它是非常有用的。這有些類似于 hack，因為它只在改變文檔注釋時才能正常工作，而修改簽名則不行。如果想要在源代碼中添加、刪除或改變任何簽名，則可能在索引、包目錄樹、繼承成員列表、用法頁或其他位置出現無效鏈接。
首先，為這次小運行新建一個目的目錄，并將 -link 和 -d 設置成相同的相對路徑： 如果原文檔位于目錄 html 中，則為：
C:> javadoc -d update -linkoffline . html com.mypackage當 javadoc 完成后，復制 update 中生成的文件并覆蓋 html 中的原文件。
背景知識： 一般地，在 javadoc 運行時，它有可能為其生成頁中出現的名字產生鏈接： 例如在簽名、@see 標記、{@link} 標記、概覽、層次、概述和索引中。有些鏈接將轉到當前運行中生成的頁，而其他鏈接有可能轉到不是在當前運行中生成的頁。
-linkoffline docURL packagelistURL
該選項為外部引用類名字創建指向文檔的鏈接，其中：
docURL 是想要鏈接到的 javadoc 生成的外部文檔的根目錄的 URL。該位置可以是相對的或絕對的 URL。
packagelistURL 是包含文檔的包列表文件所在目錄的 URL。（如果需要，可手工創建該文件。）
該選項是 -link 的一種變體。如果在運行 javadoc 時包列表文件在 docURL 位置不存在，則可使用 -linkoffline。如果知道文檔鏈接到的包名和文檔所在位置，則可以在該包列表文件實際存在于該位置之前，生成帶外部鏈接的文檔。這使得可用自己的包列表副本，生成具有適當鏈接的文檔。
當需要生成鏈接指向包名已知但尚未發布的新外部文檔（但是還沒有建立）時，這時非常有用的。這使得兩個公司可同時發布他們的文檔。它還允許生成鏈接到沒有包列表文件的外部文檔（或許它是用 Javadoc 1.0、1.1 或最高 1.2 Beta3 生成）的文檔。
注意該選項在運行 javadoc 時不需要訪問文檔 URL。因而，即使該 URL 位于 WWW 上，在生成文檔時也不需要 web 鏈接。
如下所示，要使用該選項，請指定 docURL1（javadoc 生成的外部引用類的文檔的位置）和 packagelistURL1（其包列表文件的位置）。如果它們具有相同位置，則可僅使用 -link 選項。對每個想要引用的生成文檔，需要包括 -linkoffline 一次：
C:> javadoc -linkoffline docURL1 packagelistURL1 -linkoffline docURL2 packagelistURL2例如，下面的命令使用第一個參數給定的 URL 添加鏈接，并在第二個參數給定的路徑中查找 package-list 文件。
C:> javadoc -linkoffline http://java.sun.com/products/jdk/1.2/docs/api /usr/web/work/products/jdk/1.2/docs/api/-group groupheading packagepattern:packagepattern:…
將概述頁上的包分成指定的組，每組一個表格。可以用不同的 -group 選項指定每個組。各組按命令行中指定的次序出現在頁面上，組內的包按字母排序。對于給定 -group 選項，與 packagepattern 表達式列表匹配的包出現在標題為 groupheading 的表格中。
groupheading 可以為任何文本，并可包括空格。該文本將放置在該組的表格標題中。
packagepattern 可以為任何包名，也可以為任何包名的開頭后跟星號（*）。星號是通配符，表示“匹配任何字符”。它是唯一允許的通配符。一組中可包包括多個模式，并用分號（;）分隔它們。
注意： 如果在模式或模式列表中使用星號，則模式列表必須位于引號內部，例如 "java.lang*:java.util"
如果沒有提供任何 -group 選項，則所有包都將放在一組中，并且其標題為“包”。如果所有組未包括全部帶文檔包，則剩余的任何包將出現在一個單獨的組中，且其標題為“其他包”。
例如，下面的選項將四個帶文檔包分成“核心包”、“擴展包”和“其他包”。注意后面的“點”號不出現在 “java.lang*” 中 – 包括點號，例如“java.lang.*”將忽略 java.lang 包。
C:> javadoc -group "核心包" "java.lang*:java.util" -group "擴展包" "javax.*" java.lang java.lang.reflect java.util javax.servlet java.new結果分組為：
核心包
java.lang
java.lang.reflect
java.util
擴展包
javax.servlet
其他包
java.new
-nodeprecated
防止在文檔中生成任何不鼓勵使用的 API。它執行 -nodeprecatedlist 所做的事情，并且它不在文檔其余部分生成任何不鼓勵使用的 API。當編寫代碼并不想被不鼓勵使用的代碼分心時，這是非常有用的。
-nodeprecatedlist
防止在生成文件中包含不鼓勵使用的 API 列表（deprecated-list.html）并防止在導航欄中包含該頁的鏈接。（但是，javadoc 繼續在文檔其余部分生成不鼓勵使用的 API。） 如果源代碼未包含不鼓勵使用的 API，并且想要導航欄更干凈，則它是非常有用的。
-notree
在生成文檔中忽略類/接口層次。缺省地，將產生該層次。
-noindex
在生成文檔中忽略索引。缺省地，將產生索引。
-nohelp
在輸出的每頁頂部和底部的導航欄中忽略“幫助”鏈接。
-nonavbar
防止產生導航欄、頁眉和腳注，否則它們將出現在生成頁的頂部和底部。它對“bottom”選項沒有影響。當只對內容感興趣并且沒有必要導航時，例如僅將文件轉換成 PostScript 或 PDF 以進行打印，-nonavbar 選項是非常有用的。
-helpfile path\filename
指定頂部和底部導航欄中“幫助”鏈接所鏈接到的替代幫助文件 path\filename 的路徑。不使用該選項時，Javadoc 自動創建幫助文件 help-doc.html，它在 Javadoc 中硬編碼。該選項使得可覆蓋這種缺省情況。其中 filename 可以是任何名字，不局限于 help-doc.html – Javadoc 將相應調整導航欄中的鏈接。例如：
C:> javadoc -helpfile C:\user\myhelp.html java.awt
-stylesheetfile path\filename
指定替代 HTML 樣式表單文件的路徑。不使用該選項時，Javadoc 將自動創建樣式表單文件 stylesheet.css，它在 Javadoc 中硬編碼。該選項使得可覆蓋這種缺省情況。其中 filename 可以是任何名字，不局限于 stylesheet.css。例如：
C:> javadoc -stylesheetfile C:\user\mystylesheet.css com.mypackage
-docencoding name
指定輸出 HTML 文件的編碼方式。
簡單示例
可以對整個包或單個類運行 javadoc。每個包名有一個相應的目錄名。在下面的示例中，源文件位于 C:\home\src\java\awt*java。目的目錄是 C:\home\html。
建立包的文檔
要建立包的文檔，該包的源文件（*.java）必須位于一個與該包名字相同的目錄中。如果包名由幾個標識符組成（用點號分隔），則每個標識符代表一個不同的目錄。因而，所有 java.awt 類必須位于名為 java\awt\ 的目錄中。可用如下兩種方式之一運行 javadoc – 通過改變目錄（用 cd）或使用 sourcepath 選項。不能使用通配符指定多個包。
情況 1- 換到包目錄 - 換到全限定包的父目錄。然后運行 run javadoc，并提供想要建立其文檔的一個或多個包的名字：
C:> cd C:\home\src\ C:> javadoc -d C:\home\html java.awt java.awt.event情況 2 - 從任何目錄 - 在這種情況下，當前目錄是什么沒有關系。運行 javadoc 時用 sourcepath 提供全限定包的父目錄，并提供想要建立其文檔的一個或多個包的名字：
C:> javadoc -d C:\home\html -sourcepath C:\home\src java.awt java.awt.event這兩種情況都將產生包 java.awt 和 java.awt.event 中公共和保護類和接口的 HTML 格式文檔，并將 HTML 文件保存在指定目的目錄（C:\home\html）中。因為要生成兩個或多個包，所以文檔具有三個框架 – 包列表、類列表和主頁。
建立類的文檔
要建立一個或多個源文件（.java）的文檔，這些文件不必位于特定目錄中。可以用如下兩種方式之一運行 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該示例產生類 Button、Canvas 和以 Graphics 開頭的類的 HTML 格式文檔。因為是源文件而不是包名作為參數傳遞給 javadoc，所以文檔具有兩個框架 – 類列表和主頁。
情況 2 - 改變到包的根目錄 - 當要為相同根目錄下不同子包中的單個源文件建立文檔時，這是非常有用的。改變到包的根目錄，并提供源文件相對于其根的路徑。
C:> cd /home/src/ C:> javadoc -d /home/html java/awt/Button.java java/applet/Applet.java該示例產生類 Button 和 Applet 的 HTML 格式文檔。
情況 3 - 從任何目錄 - 在這種情況下，當前目錄是什么沒有關系。運行 javadoc，并提供想要建立其文檔的 .java 文件的絕對路徑（或相對于當前目錄的相對路徑）。
C:> javadoc -d C:\home\html C:\home\src\java\awt\Button.java C:\home\src\java\awt\Graphics*.java該示例產生類 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) \ /* 添加窗口標題 */ -doctitle $(DOCTITLE) \ /* 添加文檔標題 */ -header $(HEADER) \ /* 添加運行頁眉文本 */ -bottom $(BOTTOM) \ /* 添加底部文本 */ -group $(GROUPCORE) \ /* 概述頁的核心標題 */ -group $(GROUPEXT) \ /* 概述頁的擴展標題 */ -overview overview-core.html \ /* 概述文本 */ -J-Xmx180m \ /* 180MB 內存 */ java.lang java.lang.reflect \ /* 要建立其文檔的包 */ java.util java.io java.net java.applet WINDOWTITLE = ‘Java 平臺 1.2 最終 API 規范‘ DOCTITLE = ‘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 href="http://java.sun.com/cgi-bin/bugreport.cgi"> 提交 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 選項是沒有必要的，除非文檔標題包含 HTML 標記。
如果像這里所做的一樣省略 -footer 選項，則 javadoc 將頁眉文本復制到腳注文本。
其他重要的選項是 -classpath 和 -link。
環境
CLASSPATH
提供 javadoc 用于查找用戶類文件路徑的環境變量。該環境變量將被 -classpath 選項覆蓋。Windows系統下用分號分隔目錄，例如：
.;C:\classes;C:\home\java\classes，Unix系統下使用冒號分割目錄。
另請參閱
javac
java
jdb
javah
javap
Javadoc 主頁
如何為 Javadoc 編寫文檔注釋
如有意見，請發送到： javadoc-tool@sun.com
總結
以上是生活随笔為你收集整理的javadoc - Java API 文档生成器（Windows版本）的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： ddos如何打出20G流量（ddos如何
- 下一篇： 类Unix系统下，vim各种模式之间的切