一、注釋

(1)文檔注釋的格式化

? ? ?生成的文檔是?HTML?格式，而這些?HTML?格式的標識符并不是?javadoc?加的，而是我們在寫注釋的時候寫上去的。比如，需要換行時，不是敲入一個回車符，而是寫入?＜br＞，如果要分段，就應該在段前寫入?＜p＞。 ?

? ? ?因此，格式化文檔，就是在文檔注釋中添加相應的?HTML?標識。??

? ? ?文檔注釋的正文并不是直接復制到輸出文件?(文檔的?HTML?文件)，而是讀取每一行后，刪掉前導的?*?號及?*?號以前的空格，再輸入到文檔的。

如

/** * This is first line. ＜br＞ ***** This is second line. ＜br＞ This is third line.
*/

編譯輸出后的?HTML?源碼則是?This?is?first?line.?＜br＞?This?is?second?line.?＜br＞?This?is?third?line.???

?

前導的?*?號允許連續使用多個，其效果和使用一個?*?號一樣，但多個?*?號前不能有其它字符分隔，否則分隔符及后面的?*?號都將作為文檔的內容。

還有一點需要說明，文檔注釋只說明緊接其后的類、屬性或者方法,如:

/** commnet forclass */ public classTest { }

?

(2)文檔注釋的三部分

根據在文檔中顯示的效果，文檔注釋分為三部分。先舉例如下，以便說明。

/** * show 方法的簡述* ＜p＞show 方法的詳細說明第一行＜br＞ * show 方法的詳細說明第二行* @param b true 表示顯示，false 表示隱藏* @return 沒有返回值 */ public void show(boolean b) {frame.show(b); }

1.第一部分是簡述

? ? ? ?列表中屬性名或者方法名后面那段說明就是簡述。簡述部分寫在一段文檔注釋的最前面，第一個點號?(.)?之前?(包括點號)。換句話說，就是用第一個點號分隔文檔注釋，之前是簡述，之后是第二部分和第三部分。如上例中的?“*?show?方法的簡述.”。?

有時，即使正確地以一個點號作為分隔，javadoc?仍然會出錯，把點號后面的部分也做為了第一部分。為了解決這個問題，我們可以使用一個?＜p＞?標志將第二分部分分開，如上例的“*?＜p＞show?方法的詳細說明第一行?....”。?

?

2.第二部分是詳細說明部分

? ? ? 該部分對屬性或者方法進行詳細的說明，在格式上沒有什么特殊的要求，可以包含若干個點號。?

?

3.第三部分是特殊說明部分

? ? ? 這部分包括版本說明、參數說明、返回值說明等。第三部分在上例中相應的代碼是：

* @param b true 表示顯示，false 表示隱藏??

* @return 沒有返回值?

? ? ? 除了 @param 和 @return 之外，還有其它的一些特殊標記，分別用于對類、屬性和方法的說明。

?

? ? ? 快速寫注釋的小竅門：在注釋或方法注釋前輸入“/**”，按ENTER鍵，開發軟件會自動的將param和return幫你加載出來，只用將對應 參數的功能介紹下就可以了，建議程序員最好是在開發的過程中就將注釋寫好，形成一個良好的編程習慣。

?

(3)使用 javadoc 標記

? ? ? ? javadoc?標記是插入文檔注釋中的特殊標記，它們用于標識代碼中的特殊引用。javadoc?標記由“@”及其后所跟的標記類型和專用注釋引用組成。記住了，三個部分——@、標記類型、專用注釋引用。雖然?@?和?標記類型之間有時可以用空格符分隔，但是推薦將它們緊挨著寫，以減少出錯機會。

javadoc 標記有如下一些：

標簽	說明	JDK 1.1 doclet	標準doclet	標簽類型
@author 作者	作者標識	√	√	包、 類、接口
@version 版本號	版本號	√	√	包、 類、接口
@param 參數名 描述	方法的入參名及描述信息，如入參有特別要求，可在此注釋。	√	√	構造函數、 方法
@return 描述	對函數返回值的注釋	√	√	方法
@deprecated 過期文本	標識隨著程序版本的提升，當前API已經過期，僅為了保證兼容性依然存在，以此告之開發者不應再用這個API。	√	√	包、類、接口、值域、構造函數、 方法
@throws異常類名	構造函數或方法所會拋出的異常。		√	構造函數、 方法
@exception 異常類名	同@throws。	√	√	構造函數、 方法
@see 引用	查看相關內容，如類、方法、變量等。	√	√	包、類、接口、值域、構造函數、 方法
@since 描述文本	API在什么程序的什么版本后開發支持。	√	√	包、類、接口、值域、構造函數、 方法
{@link包.類#成員 標簽}	鏈接到某個特定的成員對應的文檔中。		√	包、類、接口、值域、構造函數、 方法
{@value}	當對常量進行注釋時，如果想將其值包含在文檔中，則通過該標簽來引用常量的值。		√(JDK1.4)	靜態值域

此 外還有@serial、@serialField、@serialData、{@docRoot}、{@inheritDoc}、{@literal}、 {@code} {@value arg}幾個不常用的標簽，由于不

?

1 注釋塊標記?

1.1 標記的順序?

塊標記將采用如下順序：?

/** * @param (classes, interfaces, methods and constructors only) * @return (methods only) * @exception (@throws is a synonym added in Javadoc 1.2) * @author (classes and interfaces only, required) * @version (classes and interfaces only, required. See footnote 1) * @see * @since * @serial (or @serialField or @serialData) * @deprecated (see How and When To Deprecate APIs) */ View Code

一個塊標記可以根據需要重復出現多次，多次出現的標記按照如下順序：?

/*** @author 按照時間先后順序（chronological） * @param 按照參數定義順序（declaration） * @throws 按照異常名字的字母順序（alphabetically） * @see 按照如下順序：* @see #field * @see #Constructor(Type, Type...) * @see #Constructor(Type id, Type id...) * @see #method(Type, Type,...) * @see #method(Type id, Type, id...) * @see Class * @see Class#field * @see Class#Constructor(Type, Type...) * @see Class#Constructor(Type id, Type id) * @see Class#method(Type, Type,...) * @see Class#method(Type id, Type id,...) * @see package.Class * @see package.Class#field * @see package.Class#Constructor(Type, Type...) * @see package.Class#Constructor(Type id, Type id) * @see package.Class#method(Type, Type,...) * @see package.Class#method(Type id, Type, id) * @see package */ View Code

1.2 標記介紹?

1.2.1 @param標記?

@param后面空格后跟著參數的變量名字（不是類型），空格后跟著對該參數的描述。?

在描述中第一個名字為該變量的數據類型，表示數據類型的名次前面可以有一個冠詞如：a,an,the。如果是int類型的參數則不需要注明數據類型。例如：?

/*** @param ch the char 用用來…… * @param _image the image 用來…… * @param _num 一個數字…… */ View Code

對于參數的描述如果只是一短語，最好不要首字母大寫，結尾也不要句號。?
對于參數的描述是一個句子，最好不要首字母大寫，如果出現了句號這說明你的描述不止一句話。如果非要首字母大寫的話，必須用句號來結束句子。（英文的句號）?
添加ByRef和ByVal兩個標記，例如：?

/*** @param _image the image ByRef 用來……*/

說明該參數是引用傳遞（指針），ByVal可以省略，表示是值傳遞。?

1.2.2 @return標記?

返回為空（void）的構造函數或者函數，@return可以省略。?
如果返回值就是輸入參數，必須用與輸入參數的@param相同的描述信息。?
必要的時候注明特殊條件寫的返回值。

?1.2.3 @throws 標記?

@throws以前使用的是@exception。?
@throws的內容必須在函數的throws部分定義。

?1.2.4 @author標記?

類注釋標記。?
函數注釋里面可以不出現@author。?

1.2.5 @version?

類注釋標記。?
函數注釋里面可以不出現@version?

1.2.6 @since?

類注釋標記。?
標明該類可以運行的JDK版本?
例如：?
@since JDK1.2?

1.2.7 @deprecated?

由于某種原因而被宣布將要被廢棄的方法。?

/** * @deprecated As of JDK 1.1, replaced by * setBounds * @see #setBounds(int,int,int,int) */

3.2.8 @link標記

語法：{@link package.class#member label}?
Label為鏈接文字。?
package.class#member將被自動轉換成指向package.class的member文件的URL。

?

2. @see 的使用

@see 的句法有三種：?

@see 類名??

@see #方法名或屬性名

@see 類名#方法名或屬性名

例:

/** * @see java.lang.String * @see #str * @see #str() * @see #main(String[]) * @see java.lang.Object#toString() */ public classTestJavaDoc { private String str; public void str(){ }public static void main(String[] args){ }}

?

3、使用 @author、@version 說明類

? ? ? ?這兩個標記分別用于指明類的作者和版本。缺省情況下 javadoc 將其忽略，但命令行開關 -author 和 -version 可以修改這個功能，使其包含的信息被輸出。

這兩個標記的句法如下：???

@author 作者名??

@version 版本號???

?

? ? 其中，@author 可以多次使用，以指明多個作者，生成的文檔中每個作者之間使用逗號 (,) 隔開。@version 也可以使用多次，只有第一次有效，生成的文檔中只會顯示第一次使用 @version 指明的版本號。如下例

/** * @author MK* @versionVersion 1.00 */ public class TestJavaDoc { }

?

?4. 使用 @param、@return 和 @exception 說明方法

這三個標記都是只用于方法的。@param 描述方法的參數，@return描述方法的返回值，@exception 描述方法可能拋出的異常。它們的句法如下：?

@param 參數名 參數說明

@return 返回值說明

@exception 異常類名 說明?

? ? ? 每一個 @param 只能描述方法的一個參數，所以，如果方法需要多個參數，就需要多次使用 @param 來描述。?

一個方法中只能用一個 @return，如果文檔說明中列了多個@return，則 javadoc 編譯時會發出警告，且只有第一個 @return 在生成的文檔中有效。

? ? ? 方法可能拋出的異常應當用@exception 描述。由于一個方法可能拋出多個異常，所以可以有多個 @exception。每個 @exception 后面應有簡述的異常類名，說明中應指出拋出異常的原因。需要注意的是，異常類名應該根據源文件的 import 語句確定是寫出類名還是類全名。

示例如下：

public class TestJavaDoc { /** * @param n a switch * @param b excrescent parameter * @return true or false * @return excrescent return * @exception java.lang.Exception throw when switch is 1* @exception NullPointerException throw when parameter n is null */ public boolean fun(Integer n) throws Exception { switch (n.intValue()) { case 0: break; case 1: throw new Exception("Test Only"); default: return false; } return true; } }

?

二、開發軟件生成javadoc的方法

（1）netbeans導出javadoc方法：

?????選擇項目名稱-->右擊-->生成javadoc，即可完成生產文檔

????（文檔一般路徑在：工程名下的dist文件夾下的doc文件夾下）

?

（2）eclipse生成javadoc方法：

??????選擇項目名稱-->右擊-->Export，選擇“java”下的“javadoc”，點擊“next”，在javadoc command下的文本框中找到jdk的路徑下的javadoc.exe（例如：C:\Program Files\Java\jdk1.7.0_25\bin\javadoc.exe）

點擊“next”，在Document title中將文檔命名為自己想要的名字（例如：工程名+doc），點擊“next”，在“Extra javadoc options(...)”選項中輸入“-encoding UTF-8 -charset UTF-8 ”（這個主要是用來解決亂碼問題），點擊“finish”，即可完成文檔的生成

?????（文檔一般路徑在：工程名下的doc文件夾下）

?

（3）javadoc 命令生成javadoc方法

運行： javadoc -help 可以看到 javadoc 的用法，這里列舉常用參數如下：

用法：javadoc [options][packagenames] [sourcefiles]

1、選項options：?

-public 僅顯示 public 類和成員??

-protected 顯示protected/public 類和成員 (缺省)?

-package 顯示package/protected/public 類和成員

-private 顯示所有類和成員??

-d ＜directory＞ 輸出文件的目標目錄?

-version 包含 @version 段?

-author 包含 @author 段??

-splitindex 將索引分為每個字母對應一個文件?

-windowtitle ＜text＞ 文檔的瀏覽器窗口標題??

?

2、javadoc 編譯文檔時可以給定包列表，也可以給出源程序文件列表

例如：在 CLASSPATH 下有兩個包若干類如下：???

mk.Editor??

mk.Test???

mk.editor.Command??

mk.editor.Document??

mk.editor.View?

1)這里有兩個包 (mk 和mk.editor) 和 5 個類。那么編譯時 (Windows 環境) 可以使用如下 javadoc 命令：

javadoc ? ?mk\Test.java ? ?mk\Editor.java ? ?mk\editor\Command.java ? mk\editor\Document.java ? ?mk\editor\View.java?

這是給出 java 源文件作為編譯參數的方法，注意命令中指出的是文件路徑，應該根據實際情況改變。

?

2)也可以是給出包名作為編譯參數，如：?

javadoc ? mk ? mk.editor?

?

3、詳細選項option

-public、-protected、-package、-private 四個選項，只需要任選其一即可。它們指定的顯示類成員的程度。它們顯示的成員多少是一個包含的關系，如下：?

-private (顯示所有類和成員)??

-package (顯示package/protected/public 類和成員)?

-protected (顯示protected/public 類和成員)?

-public (僅顯示 public 類和成員)??

-d 選項允許你定義輸出目錄。如果不用 -d 定義輸出目錄，生成的文檔文件會放在當前目錄下。-d 選項的用法是?

-d 目錄名?

? ? ? 目錄名為必填項，也就是說，如果你使用了-d 參數，就一定要為它指定一個目錄。這個目錄必須已經存在了，如果還不存在，請在運行 javadoc 之前創建該目錄。

? ? ? -version 和 -author 用于控制生成文檔時是否生成@version 和 @author 指定的內容。不加這兩個參數的情況下，生成的文檔中不包含版本和作者信息。?

? ? ? -splitindex 選項將索引分為每個字母對應一個文件。默認情況下，索引文件只有一個，且該文件中包含所有索引內容。當然生成文檔內容不多的時候，這樣做非常合適，但是，如果文檔內容非常多的時候，這個索引文件將包含非常多的內容，顯得過于龐大。使用 -splitindex 會把索引文件按各索引項的第一個字母進行分類，每個字母對應一個文件。這樣，就減輕了一個索引文件的負擔。

? ? ? -windowtitle 選項為文檔指定一個標題，該標題會顯示在窗口的標題欄上。如果不指定該標題，而默認的文檔標題為“生成的文檔（無標題）”。該選項的用法是：?

? ? ? -windowtitle 標題? 標題是一串沒有包含空格的文本，因為空格符是用于分隔各參數的，所以不能包含空格。同 -d 類似，如果指定了 -windowtitle 選項，則必須指定標題文本。

?

?

總結

以上是生活随笔為你收集整理的java导出javadoc文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。