【前面的話】
這次開發項目使用jenkins做持續集成，PMD檢查代碼，Junit做單元測試，還會自動發郵件通知編譯情況，會將javadoc生成的文檔自動發到一個專門的服務器上面，每個人都可以看，所以搞得我還必須好好學習一下JavaDoc，別人看到也可以美觀一點。
【基礎知識】
一、JavaDoc簡介And基礎知識
(一) Java注釋類型
- //用於單行注釋。
- /*...*/用於多行注釋，從/*開始，到*/結束，不能嵌套。
- /**...*/則是為支持jdk工具javadoc.exe而特有的注釋語句。
說明：javadoc 工具能從java源文件中讀取第三種注釋，並能識別注釋中用@標識的一些特殊變量（見表），制作成Html格式的類說明文檔。javadoc不但能對一個 java源文件生成注釋文檔，而且能對目錄和包生成交叉鏈接的html格式的類說明文檔，十分方便。
(二)JavaDoc中出現的@字符及其意義：
1. 通用注釋
| 注釋中可以出現的關鍵字以@開始 |
意義 |
| @author |
作者名 |
| @version |
版本標識 |
| @since |
最早出現的JDK版本 |
| @deprecated |
引起不推薦使用的警告 |
| @see |
交叉參考 |
2. 方法注釋
| @return |
返回值 |
| @throws |
異常類及拋出條件 |
| @param |
參數名及其意義 |
(三)舉個例子：
我們定義一個BusTestJavaDoc類用來具體說明運用javadoc 命令時對注釋的規范。
1. 汽車類有4個屬性：
1)maxSpeed——最大速度
2)averageSpeed——平均速度
3)waterTemperature——水溫
4)Temperature——室溫
2. 兩個方法：
1)measureAverageSpeed() ——汽車的平均速度
2)measureMaxSpeed()——最大速度
3.BusTestJavaDoc.java例子：
1 /** 2 *汽車類的簡介 3 *<p>汽車類具體闡述第一行<br> 4 *汽車類具體闡述第二行 5 *@author man 6 *@author man2 7 *@version 1.0 8 *@see ship 9 *@see aircraft 10 */ 11 public class BusTestJavaDoc{ 12 /** 13 *用來標識汽車行駛當中最大速度 14 *@see #averageSpeed 15 */ 16 public int maxSpeed; 17 /**用來標識汽車行駛當中平均速度*/ 18 public int averageSpeed; 19 /**用來標識汽車行駛當中的水溫*/ 20 public int waterTemperature; 21 /**用來標識天氣溫度*/ 22 public int Temperature; 23 BusTestJavaDoc(){ 24 25 } 26 /** 27 *該方法用來測量一段時間內的平均速度 28 *@param start 起始時間 29 *@param end 截止時間 30 *@return 返回int型變量 31 *@exception java.lang.exceptionthrowwhenswitchis1 32 */ 33 public int measureAverageSpeed(int start,int end ){ 34 int aspeed=12; 35 return aspeed; 36 } 37 /** 38 * 該方法用來測量最大速度 39 */ 40 public int measureMaxSpeed(){ 41 return maxSpeed; 42 43 } 44 }
4. eclipse中導出Html文檔：
export——java——javadoc——選擇存儲位置，可以看看生產的Javadoc
二、javadoc的幾種注釋
(一)類注釋
類注釋出現在import語句之后，類定義之前，可以使用通用注釋，如下：
1 /** 2 *汽車類的簡介 3 *<p>汽車類具體闡述第一行<br> 4 *汽車類具體闡述第二行 5 *@author man 6 *@author man2 7 *@version 1.0 8 *@see ship 9 *@see aircraft 10 */ 11 public class BusTestJavaDoc{ 12 }
(二)方法注釋
每一個方法注釋必須放在所描述的方法之前，除了使用通用注釋，還可以使用方法注釋。如下：
1 /** 2 *該方法用來測量一段時間內的平均速度 3 *@param start 起始時間 4 *@param end 截止時間 5 *@return 返回int型變量 6 *@exception java.lang.exceptionthrowwhenswitchis1 7 */ 8 public int measureAverageSpeed(int start,int end ){ 9 int aspeed=12; 10 return aspeed; 11 }
(三)域注釋
只需對公有域進行注釋，可以使用通用注釋，如下：
1 /** 2 *用來標識汽車行駛當中最大速度 3 *@see #averageSpeed 4 */ 5 public int maxSpeed;
(四)包注釋與概述注釋
對於類，方法，變量的注釋放置在Java源文件中就可以了，只需使用/**···*/文檔注釋界定就可以了，如果要對包進行注釋，需要在每一個包目錄中添加一個單獨的文件。如下:
- 提供一個package.html命名的HTML文檔。標記<BODY>···</BODY>之間的所有文本都會被抽取出來。
- 提供一個package-info.java命名的java文件。這個文件必須包含一個初始的以/**和*/界定的javadoc注釋，跟隨在一個包語句之后。不應該包含更多的代碼或注釋。
如果要所有的源文件進行概述性注釋，提供一個overview.html命名的HTML文檔。這個文件位於包含所有源文件的父目錄中。標記<BODY>···</BODY>之間的所有文本都會被抽取出來。
三、文檔注釋和Html
(一)html格式生成：
生成的文檔系html款式，而這些html款式的標識符並非javadoc加的，而是寫詮釋的時候寫上去的。打個比方，需要換行時，不是敲入1個回車符，而是寫入＜br＞，要是要分段，就該當在段前寫入＜p＞。
因而，格式化文檔，不外乎在文檔詮釋中添加相應的html標簽。
文檔注釋的正文並非直接復制到輸出文檔(文檔的html文檔)，而是讀出每一行后，刪掉前導的*號及*號從前的空格，再輸入到文檔的。
(二).java文檔中是這樣的：
1 /** *thisisfirstline.<br> 2 *****thisissecondline.<br> 3 thisisthirdline. 4 */
(三)編譯輸出后的html源碼則是：
1 thisisfirstline.＜br＞ 2 thisissecondline.＜br＞ 3 thisisthirdline.
(四)在網頁上顯示是這樣的：
thisisfirstline.
thisissecondline.
thisisthirdline.
(五)說明：
前導的*號准許持續運用不止一個，其成果和運用1個*號一致，但不止一個*號前不可有其它字符分隔，不然分隔符及背后的。*號都將作為文檔的內容。*號在這里系作為左邊陲運用，如上例的第一行和第二行；要是沒有前導的*號，則邊陲從第一個有效字符開端，而不包括前面的空格，如上例第四行。
四、文檔注釋注意的細節
文檔詮釋只闡明緊接其后的類、屬性或者方式。
(一)如下例：
1 /**comment for class*/ 2 public class Test{ 3 /**comment for a attribute*/ 4 int number; 5 /**comment for a method*/ 6 public void mymethod(){......} 7 ...... 8 }
上例中的三處詮釋不外乎區別對類、屬性和方式的文檔詮釋。它們生成的文檔分別是闡明緊接其后的類、屬性、方式的。“緊接”二字特別首要，要是忽視了這一點，就很可能造成生成的文檔故障。
(二)正確例子
1 import java.lang.*; 2 /**comment for class*/ 3 public class Test{......} //此例為准確的例子
(三) 錯誤例子：
1 /**comment for class*/ 2 importjava.lang.*; 3 public class Test{......} //此例為故障的例子
這個例子只把上例的import語句和文檔詮釋局部交換了位置，效果卻不盡相同——生成的文檔中基本就找不到上述詮釋的內容了。
(四) 錯誤原因：
“/**comment for class*/”系對 Test類的闡明，把它放在“public class Test{......}”之前時，其后緊接着class Test，吻合限定，因此生成的文檔准確。可是把它和“importjava.lang.*;”改換了位置后，其后緊接的不再是類Test了，而是一個import語句。因為文檔詮釋只能闡明類、屬性和方式，import語句不在此列，因此這個文檔詮釋便被當成故障闡明省略掉了。
五、文檔注釋的三個局部
根據文檔格式在網頁上面的最終顯示，文檔注釋分為三個部分：
(一) 例子
1 /** 2 *該方法用來測量一段時間內的平均速度. 3 *<p>啊啊啊啊啊啊<br> 4 *<p>哈哈哈哈哈哈<br> 5 *@param start 起始時間 6 *@param end 截止時間 7 *@return 返回int型變量 8 *@exception java.lang.exceptionthrowwhenswitchis1 9 */ 10 public int measureAverageSpeed(int start,int end ){ 11 int aspeed=12; 12 return aspeed; 13 }
(二) 第一部分：簡述。
在Html顯示中，會將屬性和方法先進行概要列舉，如圖。
上述例子中的第二句——*該方法用來測量一段時間內的平均速度.
通過.來進行區分，在簡述部分只顯示.號之前的部分。如下圖，measureAverageSpeed方法只顯示了該方法用來測量一段時間內的平均速度.這句話，后面的“啊啊啊啊啊啊”“哈哈哈哈哈”都沒有顯示。
(三)第二部分：局部對屬性或者方式進行仔細的闡明
闡明java語句：
1 *該方法用來測量一段時間內的平均速度. 2 *<p>啊啊啊啊啊啊<br> 3 *<p>哈哈哈哈哈哈<br>
會包含簡述中的語句，如下圖：
(四)第三部分：特殊說明
java語句：
1 *@param start 起始時間 2 *@param end 截止時間 3 *@return 返回int型變量 4 *@exception java.lang.exceptionthrowwhenswitchis1
如下圖：
六、運用javadoc記號
(一) @see的運用
1. 提供類名，方法名，變量名，javadoc在文檔中插入一個超鏈接。如下：
@see com.cn.corejava.BusTestJavaDoc#measureAverageSpeed(int)
建立一個鏈接到com.cn.corejava.BusTestJavaDoc類的measureAverageSpeed(int)方法的超鏈接。
注意：一定是#來分割類名和方法名或者類名和變量名。
2. @see <a href="www.baidu.com">百度</a>
(二) 運用@author、@version闡明類
- @author,可以不止一個
- 最好只有一個
(三) 運用@param、@return和@exception闡明方式
- 這三個記號全是只用於方法的。@param描寫方式的參數，@return描寫方式的返回值，@exception描寫方式也許拋出的異常。
- 每一個@param只能描寫方式的1個參數，因此，要是方式需要不止一個參數，就需要不止一次運用@param來描寫。
- @return如下代碼：1個方式中只能用1個@return，要是文檔闡明中列了不止一個@return，則javadoc編譯時會發出正告，且只要第一個@return在生成的文檔中有效只會生成第一個.如下,生成的只有第一個:
1 *@return 返回int型變量 2 *@return 返回double型變量
4. 方法也許拋出的異常應該用@exception描寫。因為一個方式也許拋出不止一個非常，因此可以有不止一個@exception
七、Javadoc命令
(一)Javadoc生成命令
- javadoc命令
javadoc -d 文檔寄存目錄 -author -version java文檔存在目錄\源文件名.java
-author –version可以省略
2. 舉例子：
java -d D:\workspace8\JavaDoc\src D:\workspace8\JavaDoc\src\BusTestJavaDoc.java
3. 如下圖：
(二)Javadoc幫助命令
運行javadoc-help可以看到javadoc的用法，如下：
【建議風格】
一、 格式
- 一般形式：
這樣：
/** * Multiple lines of Javadoc text are written here, * wrapped normally... */ public int method(String p1) { ... }
或這樣：
/** An especially short bit of Javadoc. */
- 段落
空行(即，只包含最左側星號的行)會出現在段落之間和Javadoc標記(@XXX)之前(如果有的話)。除了第一個段落，每個段落第一個單詞前都有標簽<p>，並且它和第一個單詞間沒有空格。
- Javadoc標記
標准的Javadoc標記按以下順序出現：@param, @return, @throws, @deprecated, 前面這4種標記如果出現，描述都不能為空。當描述無法在一行中容納，連續行需要至少再縮進4個空格。
二、摘要片段
- 每個類或成員的Javadoc以一個簡短的摘要片段開始。這個片段是非常重要的，在某些情況下，它是唯一出現的文本，比如在類和方法索引中。
- 這只是一個小片段，可以是一個名詞短語或動詞短語，但不是一個完整的句子。它不會以A {@code Foo} is a...或This method returns...開頭, 它也不會是一個完整的祈使句，如Save the record...。然而，由於開頭大寫及被加了標點，它看起來就像是個完整的句子。
- Tip：一個常見的錯誤是把簡單的Javadoc寫成
/** @return the customer ID */，這是不正確的。它應該寫成/** Returns the customer ID. */。
三、哪里需要使用Javadoc
至少在每個public類及它的每個public和protected成員處使用Javadoc。
例外：
- 不言自明的方法
對於簡單明顯的方法如getFoo，Javadoc是可選的(即，是可以不寫的)。這種情況下除了 寫“Returns the foo”，確實也沒有什么值得寫了。
單元測試類中的測試方法可能是不言自明的最常見例子了，我們通常可以從這些方法的描述性命名中知道它是干什么的，因此不需要額外的文檔說明。
- 重載
如果一個方法重載了超類中的方法，那么Javadoc並非必需的。
- 可選的Javadoc
對於包外不可見的類和方法，如有需要，也是要使用Javadoc的。如果一個注釋是用來定義一個類，方法，字段的整體目的或行為，那么這個注釋應該寫成Javadoc，這樣更統一更友好。
【參考資料】
- 這篇文章主要是學習了《javadoc__用法_很詳細》這個文檔
【后面的話】
加油吧。
——TT