目錄 html
前言
一. Java 文檔和 javadoc
二. 文檔註釋的格式
1. 文檔註釋的格式化
2. 文檔註釋的三部分
三. 使用 javadoc 標記
1. @see 的使用
2. 使用 @author、@version 說明類
3. 使用 @param、@return 和 @exception 說明方法
四. javadoc 命令
java
Java 的語法與 C++ 及爲類似,那麼,你知道 Java 的註釋有幾種嗎?是兩種? 瀏覽器
// 註釋一行
/* ...... */ 註釋若干行安全
不徹底對,除了以上兩種以外,還有第三種,文檔註釋:框架
/** ...... */ 註釋若干行,並寫入 javadoc 文檔工具
一般這種註釋的多行寫法以下:spa
/**
* .........
* .........
*/命令行
暫停,暫停!這第三種註釋有什麼用?javadoc 又是什麼東西?code
好,那就讓我告訴你——
Java 程序員都應該知道使用 JDK 開發,最好的幫助信息就來自 SUN 發佈的 Java 文檔。它分包、分類詳細的提供了各方法、屬性的幫助信息,具備詳細的類樹信息、索引信息等,並提供了許多相關類之間的關係,如繼承、實現接口、引用等。
Java 文檔全是由一些 html 文件組織起來的,在 SUM 的站點上能夠下載它們的壓縮包。可是你確定想不到,這些文檔咱們能夠本身生成。——就此打住,再吊一次胃口。
安裝了 JDK 以後,安裝目錄下有一個 src.jar 文件或者 src.zip 文件,它們都是以 ZIP 格式壓縮的,可使用 WinZip 解壓。解壓以後,咱們就能夠看到分目錄放的全是 .java 文件。是了,這些就是 Java 運行類的源碼了,很是完整,連註釋都寫得一清二楚……不過,怎麼看這些註釋都有點似曾相識的感受?
這就不奇怪了,咱們的迷底也快要揭開了。若是你仔細對比一下 .java 源文件中的文檔註釋 (/** ... */) 和 Java 文檔的內容,你會發現它們就是同樣的。Java 文檔只是還在格式和排版上下了些功夫。再仔細一點,你會發現 .java 源文件中的註釋還帶有 HTML 標識,如 、
、 等,在 Java 文檔中,該出現這些標識的地方,已經按標識的的定義進行了排版。
終於真像大白了,原來 Java 文檔是來自這些註釋。難怪這些註釋叫作文檔註釋呢!不過,是什麼工具把這些註釋變成文檔的呢?
是該請出 javadoc 的時候了。在 JDK 的 bin 目錄下你能夠找到 javadoc,若是是 Windows 下的 JDK,它的文件名爲 javadoc.exe。使用 javdoc 編譯 .java 源文件時,它會讀出 .java 源文件中的文檔註釋,並按照必定的規則與 Java 源程序一塊兒進行編譯,生成文檔。
介紹 javadoc 的編譯命令以前,仍是先了解一下文檔註釋的格式吧。不過爲了可以編譯下面提到的若干例子,這裏先介紹一條 javadoc 命令:
javadoc -d 文檔存放目錄 -author -version 源文件名.java
這條命令編譯一個名爲 「源文件名.java」的 java 源文件,並將生成的文檔存放在「文檔存放目錄」指定的目錄下,生成的文檔中 index.html 就是文檔的首頁。-author 和 -version 兩個選項能夠省略。
文檔註釋能夠用於對類、屬性、方法等進行說明。寫文檔註釋時除了須要使用 /** .... */ 限定以外,還須要注意註釋內部的一些細節問題。
生成的文檔是 HTML 格式,而這些 HTML 格式的標識符並非 javadoc 加的,而是咱們在寫註釋的時候寫上去的。好比,須要換行時,不是敲入一個回車符,而是寫入
,若是要分段,就應該在段前寫入
。
所以,格式化文檔,就是在文檔註釋中添加相應的 HTML 標識。
文檔註釋的正文並非直接複製到輸出文件 (文檔的 HTML 文件),而是讀取每一行後,刪掉前導的 * 號及 * 號之前的空格,再輸入到文檔的。如
/** * This is first line. ***** This is second line. This is third line. */ |
編譯輸出後的 HTML 源碼則是
This is first line. This is second line. This is third line. |
前導的 * 號容許連續使用多個,其效果和使用一個 * 號同樣,但多個 * 號前不能有其它字符分隔,不然分隔符及後面的 * 號都將做爲文檔的內容。* 號在這裏是做爲左邊界使用,如上例的第一行和第二行;若是沒有前導的 * 號,則邊界從第一個有效字符開始,而不包括前面的空格,如上例第三行。
還有一點須要說明,文檔註釋只說明緊接其後的類、屬性或者方法。以下例:
public class Test { int number; public void myMethod() { ...... } ...... } |
上例中的三處註釋就是分別對類、屬性和方法的文檔註釋。它們生成的文檔分別是說明緊接其後的類、屬性、方法的。「緊接」二字尤爲重要,若是忽略了這一點,就極可能形成生成的文檔錯誤。如
import java.lang.*; public class Test { ...... } |
這個文檔註釋將生成正確的文檔。但只須要改變其中兩行的位置,變成下例,就會出錯:
import java.lang.*; public class Test { ...... } |
這個例子只把上例的 import 語句和文檔註釋部分交換了位置,結果卻大不相同——生成的文檔中根本就找不到上述註釋的內容了。緣由何在?
「/** commnet for class */」是對 class Test 的說明,把它放在「public class Test { ...... }」以前時,其後緊接着 class Test,符合規則,因此生成的文檔正確。可是把它和「import java.lang.*;」調換了位置後,其後緊接的就是不 class Test 了,而是一個 import 語句。因爲文檔註釋只能說明類、屬性和方法,import 語句不在此列,因此這個文檔註釋就被看成錯誤說明省略掉了。
根據在文檔中顯示的效果,文檔註釋分爲三部分。先舉例以下,以便說明。
public void show(boolean b) { frame.show(b); } |
第一部分是簡述。文檔中,對於屬性和方法都是先有一個列表,而後纔在後面一個一個的詳細的說明。列表中屬性名或者方法名後面那段說明就是簡述。以下圖中被紅框框選的部分:
簡述部分寫在一段文檔註釋的最前面,第一個點號 (.) 以前 (包括點號)。換句話說,就是用第一個點號分隔文檔註釋,以前是簡述,以後是第二部分和第三部分。如上例中的 「* show 方法的簡述.」。
有時,即便正確地以一個點號做爲分隔,javadoc 仍然會出錯,把點號後面的部分也作爲了第一部分。爲了解決這個問題,咱們可使用一個
標誌將第二分部分開爲下一段,如上例的「*
show 方法的詳細說明第一行 ....」。除此以外,咱們也可使用
來分隔。
第二部分是詳細說明部分。該部分對屬性或者方法進行詳細的說明,在格式上沒有什麼特殊的要求,能夠包含若干個點號。它在文檔中的位置以下圖所示:
這部分文檔在上例中相應的代碼是:
* show 方法的簡述.
*
show 方法的詳細說明第一行
* show 方法的詳細說明第二行
發現什麼了?對了,簡述也在其中。這一點要記住了,不要多此一舉——在詳細說明部分中再寫一次簡述哦!
第三部分是特殊說明部分。這部分包括版本說明、參數說明、返回值說明等。它在文檔中的位置:
第三部分在上例中相應的代碼是
* @param b true 表示顯示,false 表示隱藏
* @return 沒有返回值
除了 @param 和 @return 以外,還有其它的一些特殊標記,分別用於對類、屬性和方法的說明……不要推我,我立刻就說。
javadoc 標記是插入文檔註釋中的特殊標記,它們用於標識代碼中的特殊引用。javadoc 標記由「@」及其後所跟的標記類型和專用註釋引用組成。記住了,三個部分——@、標記類型、專用註釋引用。不過我寧願把它分紅兩部分:@ 和標記類型、專用註釋引用。雖然 @ 和 標記類型之間有時能夠用空格符分隔,可是我寧願始終將它們緊挨着寫,以減小出錯機會。
javadoc 標記有以下一些:
|
下面詳細說明各標記。
@see 的句法有三種:
@see 類名
@see #方法名或屬性名
@see 類名#方法名或屬性名
類名,能夠根據須要只寫出類名 (如 String) 或者寫出類全名 (如 java.lang.String)。那麼何時只須要寫出類名,何時須要寫出類全名呢?
若是 java 源文件中的 import 語句包含了的類,能夠只寫出類名,若是沒有包含,則須要寫出類全名。java.lang 也已經默認被包含了。這和 javac 編譯 java 源文件時的規定同樣,因此能夠簡單的用 javac 編譯來判斷,源程序中 javac 能找到的類,javadoc 也必定能找到;javac 找不到的類,javadoc 也找不到,這就須要使用類全名了。
方法名或者屬性名,若是是屬性名,則只須要寫出屬性名便可;若是是方法名,則須要寫出方法名以及參數類型,沒有參數的方法,須要寫出一對括號。如
成員類型 | 成員名稱及參數 | @see 句法 |
屬性 | number | @see number |
屬性 | count | @see count |
方法 | count() | @see count() |
方法 | show(boolean b) | @see show(boolean) |
方法 | main(String[] args) | @see main(String[]) |
有時也能夠偷懶:假如上例中,沒有 count 這一屬性,那麼參考方法 count() 就能夠簡寫成 @see count。不過,爲了安全起見,仍是寫全 @see count() 比較好。
@see 的第二個句法和第三個句法都是轉向方法或者屬性的參考,它們有什麼區別呢?
第二個句法中沒有指出類名,則默認爲當前類。因此它定義的參考,都轉向本類中的屬性或者方法。而第三個句法中指出了類名,則還能夠轉向其它類的屬性或者方法。
關於 @see 標記,咱們舉個例說明。因爲 @see 在對類說明、對屬性說明、對方法說明時用法都同樣,因此這裏只以對類說明爲例。
public class TestJavaDoc { } |
生成的文檔的相關部分以下圖:
String 和 StringBuffer 都是在 java.lang 包中,因爲這個包是默認導入了的,因此這兩個類能夠直接寫類名,也能夠寫類全名。str、str() 爲同名屬性和方法,因此方法名須要用 () 區分。main 是帶參數的方法,因此在 () 中指明瞭參數類型。toString() 雖然在本類中也有 (從 Object 繼承的),但咱們是想參考 Object 類的 toString() 方法,因此使用了 Object#toString()。
奇怪的是,爲何其中只有 str、str() 和 main(String[]) 變成了連接呢?那是由於編譯時沒有把 java.lang 包或者 Stirng、StringBuffer、Object 三個類的源文件一塊兒加入編譯,因此,生成的文檔沒有關於那三個類的信息,也就不能夠創建連接了。後面講解 javadoc 編譯命令的時候還會詳細說明。
上例中若是去把類中的 str 屬性去掉,那麼生成的文檔又會有什麼變化呢?你會發現,原來是 str, str(),而如今變成了 str(), str(),由於 str 屬性已經沒有了,因此 str 也表示方法 str()。
這兩個標記分別用於指明類的做者和版本。缺省狀況下 javadoc 將其忽略,但命令行開關 -author 和 -version 能夠修改這個功能,使其包含的信息被輸出。這兩個標記的句法以下:
@author 做者名
@version 版本號
其中,@author 能夠屢次使用,以指明多個做者,生成的文檔中每一個做者之間使用逗號 (,) 隔開。@version 也可使用屢次,只有第一次有效,生成的文檔中只會顯示第一次使用 @version 指明的版本號。以下例
public class TestJavaDoc { } |
生成文檔的相關部分如圖:
從生成文檔的圖示中能夠看出,兩個 @author 語句都被編譯,在文檔中生成了做者列表。而兩個 @version 語句中只有第一句被編譯了,只生成了一個版本號。
從圖上看,做者列表是以逗號分隔的,若是我想分行顯示怎麼辦?另外,若是我想顯示兩個以上的版本號又該怎麼辦?
——咱們能夠將上述兩條 @author 語句合爲一句,把兩個 @version 語句也合爲一句:
@author Fancy
Bird
@version Version 1.00
Version 2.00
結果如圖:
咱們這樣作即達到了目的,又沒有破壞規則。@author 以後的做者名和 @version 以後的版本號均可以是用戶本身定義的任何 HTML 格式,因此咱們可使用
標記將其分行顯示。同時,在一個 @version 中指明兩個用
分隔的版本號,也沒有破壞只顯示第一個 @version 內容的規則。
3. 使用 @param、@return 和 @exception 說明方法
這三個標記都是隻用於方法的。@param 描述方法的參數,@return 描述方法的返回值,@exception 描述方法可能拋出的異常。它們的句法以下:
@param 參數名 參數說明
@return 返回值說明
@exception 異常類名 說明
每個 @param 只能描述方法的一個參數,因此,若是方法須要多個參數,就須要屢次使用 @param 來描述。
一個方法中只能用一個 @return,若是文檔說明中列了多個 @return,則 javadoc 編譯時會發出警告,且只有第一個 @return 在生成的文檔中有效。
方法可能拋出的異常應當用 @exception 描述。因爲一個方法可能拋出多個異常,因此能夠有多個 @exception。每一個 @exception 後面應有簡述的異常類名,說明中應指出拋出異常的緣由。須要注意的是,異常類名應該根據源文件的 import 語句肯定是寫出類名仍是類全名。 示例以下:
public class TestJavaDoc { 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 編譯生成的文檔相關部分以下圖:
能夠看到,上例中 @param b excrescent parameter 一句是多餘的,由於參數只是一個 n,並無一個 b可是 javadoc 編譯時並無檢查。所以,寫文檔註釋時必定要正確匹配參數表與方法中正式參數表的項目。若是方法參數表中的參數是 a,文檔中卻給出對參數 x 的解釋,或者再多出一個參數 i,就會讓人摸不着頭腦了。@exceptin 也是同樣。
上例程序中並無拋出一個 NullPointerException,可是文檔註釋中爲何要寫上這麼一句呢,難道又是爲了演示?這不是爲了演示描述多餘的異常也能經過編譯,而是爲了說明寫異常說明時應考運行時 (RunTime) 異常的可能性。上例程序中,若是參數 n 是給的一個空值 (null),那麼程序會在運行的時候拋出一個 NullPointerException,所以,在文檔註釋中添加了對 NullPointerException 的說明。
上例中的 @return 語句有兩個,可是根據規則,同一個方法中,只有第一個 @return 有效,其他的會被 javadoc 忽略。因此生成的文檔中沒有出現第二個 @return 的描述。
講到這裏,該怎麼寫文檔註釋你應該已經清楚了,下面就開始講解 javadoc 的經常使用命令。
運行 javadoc -help 能夠看到 javadoc 的用法,這裏列舉經常使用參數以下:
用法:
javadoc [options] [packagenames] [sourcefiles]
選項:
-public | 僅顯示 public 類和成員 | |
-protected | 顯示 protected/public 類和成員 (缺省) | |
-package | 顯示 package/protected/public 類和成員 | |
-private | 顯示全部類和成員 | |
-d | 輸出文件的目標目錄 | |
-version | 包含 @version 段 | |
-author | 包含 @author 段 | |
-splitindex | 將索引分爲每一個字母對應一個文件 | |
-windowtitle | 文檔的瀏覽器窗口標題 |
javadoc 編譯文檔時能夠給定包列表,也能夠給出源程序文件列表。例如在 CLASSPATH 下有兩個包若干類以下:
fancy.Editor
fancy.Test
fancy.editor.ECommand
fancy.editor.EDocument
fancy.editor.EView
這裏有兩個包 (fancy 和 fancy.editor) 和 5 個類。那麼編譯時 (Windows 環境) 可使用以下 javadoc 命令:
javadoc fancy/Test.java fancy/Editor.java fancy/editor/ECommand.java fancy/editor/EDocument.java fancy/editor/EView.java
這是給出 java 源文件做爲編譯參數的方法,注意命令中指出的是文件路徑,應該根據實際狀況改變。也能夠是給出包名做爲編譯參數,如:
javadoc fancy fancy.editor
用瀏覽器打開生成文檔的 index.html 文件便可發現兩種方式編譯結果的不一樣,以下圖:
用第二條命令生成的文檔被框架分紅了三部分:包列表、類列表和類說明。在包列表中選擇了某個包以後,類列表中就會列出該包中的全部類;在類列表中選擇了某個類以後,類說明部分就會顯示出該類的詳細文檔。而用第一條命令生成的文檔只有兩部分,類列表和類說明,沒有包列表。這就是兩種方式生成文檔的最大區別了。
下面再來細說選項。
-public、-protected、-package、-private 四個選項,只須要任選其一便可。它們指定的顯示類成員的程度。它們顯示的成員多少是一個包含的關係,以下表:
-private (顯示全部類和成員) | |||||
|
-d 選項容許你定義輸出目錄。若是不用 -d 定義輸出目錄,生成的文檔文件會放在當前目錄下。-d 選項的用法是
-d 目錄名
目錄名爲必填項,也就是說,若是你使用了 -d 參數,就必定要爲它指定一個目錄。這個目錄必須已經存在了,若是還不存在,請在運行 javadoc 以前建立該目錄。
-version 和 -author 用於控制生成文檔時是否生成 @version 和 @author 指定的內容。不加這兩個參數的狀況下,生成的文檔中不包含版本和做者信息。
-splitindex 選項將索引分爲每一個字母對應一個文件。默認狀況下,索引文件只有一個,且該文件中包含全部索引內容。固然生成文檔內容很少的時候,這樣作很是合適,可是,若是文檔內容很是多的時候,這個索引文件將包含很是多的內容,顯得過於龐大。使用 -splitindex 會把索引文件按各索引項的第一個字母進行分類,每一個字母對應一個文件。這樣,就減輕了一個索引文件的負擔。
-windowtitle 選項爲文檔指定一個標題,該標題會顯示在窗口的標題欄上。若是不指定該標題,而默認的文檔標題爲「生成的文檔(無標題)」。該選項的用法是:
-windowtitle 標題
標題是一串沒有包含空格的文本,由於空格符是用於分隔各參數的,因此不能包含空格。同 -d 相似,若是指定了 -windowtitle 選項,則必須指定標題文本。
到此爲止,Java 文檔和 javadoc 就介紹完了。javadoc 真的能讓咱們在 Java 註釋上作文章——生成開發文檔。