如果要想使一個API真正可用，就必須為其編寫文檔。傳統意義上的API文檔是手動生成的，所以保持文檔與代碼同步是一件很繁瑣的事情。Java環境提供了一種被稱為Javadoc的實用工具，從而使這項任務變得很容易。Javadoc利用特格式的文檔注釋，根據源代碼自動產生API文檔。

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

da74efb0892d41c9ad951d974391789b.png

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

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

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

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

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

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

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

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

文檔注釋示例：

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

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

/**
 * @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
}

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

/**
 * 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;
}

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

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();
}

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

簡而言之，要為API編寫文檔，文檔注釋是最好、最有效的途徑。對于所有可導出的API元素來說，使用文檔注釋應該被看作是強制性的。要采用一致的風格來遵循標準的約定。在文檔注釋內部出現任何HTML標簽都是允許的，但是HTML字符必須要經過轉義。