java中的註釋規範，生成javadoc
java中的註釋，大家應該已經很熟悉了。
文件註釋可以用於對類、屬性、方法等進行說明。寫文件註釋時除了需要使用 /** .... */ 限定之外，還需要注意註釋內部的一些細節問題。
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 voidshow(boolean b) { frame.show(b); }
第一部分是簡述，列表中屬性名或者方法名後面那段說明就是簡述。簡述部分寫在一段文件註釋的最前面，第一個點號 (.) 之前 (包括點號)。換句話說，就是用第一個點號分隔文件註釋，之前是簡述，之後是第二部分和第三部分。如上例中的 “* show 方法的簡述.”。
有時，即使正確地以一個點號作為分隔，javadoc 仍然會出錯，把點號後面的部分也做為了第一部分。為了解決這個問題，我們可以使用一個 ＜p＞ 標誌將第二分部分分開，如上例的“* ＜p＞show 方法的詳細說明第一行 ....”。
第二部分是詳細說明部分。該部分對屬性或者方法進行詳細的說明，在格式上沒有什麼特殊的要求，可以包含若干個點號。
第三部分是特殊說明部分。這部分包括版本說明、引數說明、返回值說明等。第三部分在上例中相應的程式碼是：
* @param b true 表示顯示，false 表示隱藏
* @return 沒有返回值
除了 @param 和 @return 之外，還有其它的一些特殊標記，分別用於對類、屬性和方法的說明。
三. 使用 javadoc 標記
javadoc 標記是插入文件註釋中的特殊標記，它們用於標識程式碼中的特殊引用。javadoc 標記由“@”及其後所跟的標記型別和專用註釋引用組成。記住了，三個部分——@、標記型別、專用註釋引用。雖然 @ 和 標記型別之間有時可以用空格符分隔，但是推薦將它們緊挨著寫，以減少出錯機會。
javadoc 標記有如下一些：
標記 用於 作用
@author 對類的說明 標明開發該類模組的作者
@version 對類的說明 標明該類模組的版本
@see 對類、屬性、方法的說明 參考轉向，也就是相關主題
@param 對方法的說明 對方法中某引數的說明
@return 對方法的說明 對方法返回值的說明
@exception 對方法的說明 對方法可能丟擲的異常進行說明
1 @see 的使用
@see 的句法有三種：
@see 類名
@see #方法名或屬性名
@see 類名#方法名或屬性名
例:
/**
* @see java.lang.String
* @see #str
* @see #str()
* @see #main(String[])
* @see java.lang.Object#toString()
*/
public classTestJavaDoc {
private Stringstr;
public voidstr(){ }
public staticvoid main(String[] args){ }
}
生成的文件的相關部分如下圖
2. 使用 @author、@version 說明類
這兩個標記分別用於指明類的作者和版本。預設情況下 javadoc 將其忽略，但命令列開關 -author 和 -version 可以修改這個功能，使其包含的資訊被輸出。
這兩個標記的句法如下：
@author 作者名
@version 版本號
其中，@author 可以多次使用，以指明多個作者，生成的文件中每個作者之間使用逗號 (,) 隔開。@version 也可以使用多次，只有第一次有效，生成的文件中只會顯示第一次使用 @version 指明的版本號。如下例
/**
* @author Fancy
* @author Bird
* @versionVersion 1.00
* @versionVersion 2.00
*/
public classTestJavaDoc {}
生成文件的相關部分如圖
3. 使用 @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 編譯生成的文件相關部分如下圖：
四. javadoc 命令
執行： javadoc -help 可以看到 javadoc 的用法，這裡列舉常用引數如下：
用法：javadoc [options][packagenames] [sourcefiles]
選項：
-public 僅顯示 public 類和成員
-protected 顯示protected/public 類和成員 (預設)
-package 顯示package/protected/public 類和成員
-private 顯示所有類和成員
-d ＜directory＞ 輸出檔案的目標目錄
-version 包含 @version 段
-author 包含 @author 段
-splitindex 將索引分為每個字母對應一個檔案
-windowtitle ＜text＞ 文件的瀏覽器視窗標題
javadoc 編譯文件時可以給定包列表，也可以給出源程式檔案列表。例如在 CLASSPATH 下有兩個包若干類如下：
fancy.Editor fancy.Test
fancy.editor.ECommand
fancy.editor.EDocument
fancy.editor.EView 這裡有兩個包 (fancy 和fancy.editor) 和 5 個類。那麼編譯時 (Windows 環境) 可以使用如下 javadoc 命令：
javadocfancy\Test.java fancy\Editor.java fancy\editor\ECommand.java
fancy\editor\EDocument.javafancy\editor\EView.java
這是給出 java 原始檔作為編譯引數的方法，注意命令中指出的是檔案路徑，應該根據實際情況改變。也可以是給出包名作為編譯引數，如：
javadoc fancyfancy.editor
用瀏覽器開啟生成文件的index.html 檔案即可發現兩種方式編譯結果的不同，如下圖：
用第二條命令生成的文件被框架分成了三部分：包列表、類列表和類說明。在包列表中選擇了某個包之後，類列表中就會列出該包中的所有類；在類列表中選擇了某個類之後，類說明部分就會顯示出該類的詳細文件
下面再來細說選項。
-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 選項，則必須指定標題文字。