如果要想使一個(gè)API真正可用，就必須為其編寫文檔。傳統(tǒng)意義上的API文檔是手動(dòng)生成的，所以保持文檔與代碼同步是一件很繁瑣的事情。Java環(huán)境提供了一種被稱為Javadoc的實(shí)用工具，從而使這項(xiàng)任務(wù)變得很容易。Javadoc利用特格式的文檔注釋，根據(jù)源代碼自動(dòng)產(chǎn)生API文檔。

如何使用Javadoc？相關(guān)資料：http://blog.csdn.net/nothing0318/article/details/7258523
1.在myeclipse中點(diǎn)擊導(dǎo)航欄中的 project->Generate javadoc彈出如下界面，然后勾選需要生成文檔的包以及生成文檔的位置。

da74efb0892d41c9ad951d974391789b.png

2.在dos命令提示符中輸入：javadoc -d myhelp -author -version Register.java（也可以編譯整個(gè)文件夾，javadoc -d myhelp -author -version test）
-d 表示生成的目錄位置，myhelp表示生成文檔所在當(dāng)前目錄下的文件夾名
-author是作者的名字 -version是版本號（這兩項(xiàng)非必填項(xiàng)，不寫的話不會生成相應(yīng)的文檔注釋內(nèi)容）
ps:如果注釋中有中文，需要在dos命令中加入-encoding utf-8 -charset utf-8

基礎(chǔ)知識：
1./**this is a description*/注釋若干行，并寫入 javadoc 文檔
2.文檔注釋三部分：

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

第一部分是簡述。文檔中，對于屬性和方法都是先有一個(gè)列表，然后才在后面一個(gè)一個(gè)的詳細(xì)的說明

第二部分是詳細(xì)說明部分。該部分對屬性或者方法進(jìn)行詳細(xì)的說明，在格式上沒有什么特殊的要求，可以包含若干個(gè)點(diǎn)號。

第三部分是特殊說明部分。這部分包括版本說明、參數(shù)說明、返回值說明等。

• @param b true 表示顯示，false 表示隱藏
• @return 沒有返回值

添加文檔注釋規(guī)范：
一、為了正確地編寫API文檔，必須在每個(gè)被導(dǎo)出的類、接口、構(gòu)造器、方法和域聲明之前增加一個(gè)文檔注釋。
二、方法的文檔注釋應(yīng)該簡潔的描述出它和客戶端之間的約定。這個(gè)約定應(yīng)該說明這個(gè)方法做了什么，而不是說明它是如何完成這項(xiàng)工作的。文檔注釋應(yīng)該列舉如下內(nèi)容：
1.前提條件（precondition） 前提條件是指為了使客戶能夠調(diào)用這個(gè)方法，而必須滿足的條件；
2.后置條件（postcondition） 所謂后置條件是指在調(diào)用成功完成之后，哪些條件必須要滿足；
3.副作用（side effect） 副作用是指系統(tǒng)狀態(tài)中可以觀察到的變化，它不是為了獲得后置條件而明確要求的變化；
4.類或者方法的線程安全性（thread safety）（詳見70條） 當(dāng)一個(gè)類的實(shí)例或者靜態(tài)方法被并發(fā)使用時(shí)，這個(gè)類行為的并發(fā)情況。

文檔注釋示例：

/** 
 * Returns the element at the specified position in this list. 
 * 
 * <p>This method is <i>not</i> guaranteed to run in constant 
 * time. In some implementations it may run in time proportional 
 * to the element position. 
 * 
 * @param index index of element to return; must be 
 *        non-negative and less than the size of this list 
 * @return the element at the specified position in this list 
 * @throws IndexOutOfBoundsException if the index is out of range 
 *         ({@code index < 0 || index >= this.size()}) 
 */  
 E get(int index);

?文檔注釋必須以/**開頭，否則Javadoc無法識別。
?文檔注釋第一句話作為概要描述。概要描述必須獨(dú)立地描述目標(biāo)元素的功能，同一個(gè)類或接口中的任意兩個(gè)成員或構(gòu)造器，不應(yīng)該具有相同的概要描述。即使是重載方法也不行。
?每個(gè)參數(shù)都應(yīng)該有一個(gè)@param標(biāo)簽，標(biāo)簽后面第一個(gè)單詞為參數(shù)名稱，接著是對該參數(shù)的解釋和要求。
?返回類型非void的方法都應(yīng)該有一個(gè)@return標(biāo)簽，描述返回值所表示的內(nèi)容。
?該方法可能拋出的每一個(gè)異常，無論是受檢異常還是非受檢異常，都要對應(yīng)一個(gè)@throws標(biāo)簽。標(biāo)簽后面第一個(gè)單詞為異常類型，接著是一句話，應(yīng)該以if開頭，描述該異常將在什么情況下被拋出。@param、@return和@throws都不以句點(diǎn)結(jié)束。
? @code標(biāo)簽可用于任何需要展示代碼的地方，被該標(biāo)簽包圍的內(nèi)容會以特殊的字體顯示，并且不對其中內(nèi)容做任何HTML解析。
?按慣例，單詞“this”用在實(shí)例方法的文檔注釋中時(shí)，應(yīng)該始終是指方法調(diào)用所在的對象。
?可以用@literal標(biāo)簽展示包含HTML元字符的句子。它除了不改變顯示樣式外，其余效果和@code一樣。

Java 1.5發(fā)行版本中增加的三個(gè)特性在文檔注釋中需要特別小心：泛型、枚舉和注解。當(dāng)為泛型或者方法編寫文檔時(shí)，確保要在文檔中說明所有的類型參數(shù)。

/**
 * @author zhaiyanming
 * @version 1.0
 * @param <K> the type of keys maintained by the map
 * @param <V> the type of mapped values
 */
public interface Map<K, V> {
    //dosomething
}

當(dāng)為枚舉類型編寫文檔時(shí)，要確保在文檔中說明常量，以及類型，還有任何公有的方法。

/**
 * three primary colours
 * @author zhaiyanming
 * @version 1.0
 * return enum
 */
public enum Color {
    /** Red, the color of blood. */
    RED,
    /** Green, the color of grass.  */
    GREEN,
    /** Blue, the color of sea. */
    BLUE;
}

為注解類型編寫文檔時(shí)，要確保在文檔中說明所有成員，以及本身類型。對于該類型的概要描述，要使用一個(gè)動(dòng)詞短語，說明當(dāng)程序元素具有這種類型的注解時(shí)它表示什么意思。

import java.lang.annotation.ElementType;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Indicates that the annotated method is a test method that
 * must throw the designated exception to succeed.
 * @author zhaiyanming
 * @version 1.0
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
    /**The exception that the annotated test method must throw
     * in order to pass. (The test is permitted to throw any
     * subtype of the type described by this class object.) */
    Class<? extends Exception> value();
}

類的導(dǎo)出API有兩個(gè)容易被人忽略的特征：
1.類是否是線程安全的應(yīng)該在文檔中對它的線程安全級別進(jìn)行說明。（如70條所述）
2.如果類是可序列化的，就應(yīng)該在文檔中說明它的序列化形式。（如第75條所述）

簡而言之，要為API編寫文檔，文檔注釋是最好、最有效的途徑。對于所有可導(dǎo)出的API元素來說，使用文檔注釋應(yīng)該被看作是強(qiáng)制性的。要采用一致的風(fēng)格來遵循標(biāo)準(zhǔn)的約定。在文檔注釋內(nèi)部出現(xiàn)任何HTML標(biāo)簽都是允許的，但是HTML字符必須要經(jīng)過轉(zhuǎn)義。