只要我們按照Javadoc 註釋規則,在編碼完成後,Javadoc 就能夠幫我們從源代碼中生成相應的Html 格式的API開發文檔。這些文檔可以通過Web瀏覽器來查看。點擊Oracle規範,我根據SDK內源碼的註釋習慣,將常用的javadoc tag進行了整理,見下:
tags
在給公共類或公共方法添加註釋的時候,第一句話應該是一個簡短的摘要。注意左側不要緊挨 * 號,要有一個空格。如果註釋有多個段落,使用< p>段落標記來分隔段落。我們還可使用< tt>標籤來讓特定的內容呈現出等寬的文本效果。見下:
/**
* 第一句話是這個方法的<tt>簡短</tt>摘要。
* 如果這個描述太長,記得換行。
*
* <p>如果多個段落可以這樣
* 當回車的時候與標籤首部對齊即可
*/
public void test(){}
如果註釋描述裏需要包含一個列表,一組選項等,我們可以使用< li>標籤來標識,注意標籤後不需要空格,見下:
/**
* 第一句話是這個方法的簡短摘要。
* 如果這個描述太長,記得換行。
*
* <p>如果多個段落可以這樣
*
* <ul>
* <li>這是列表1
* <li>這是列表2...
* 同樣回車後與標籤對齊即可
* </ul>
*/
public void test(){}
@param 是用來描述方法的輸入參數。注意在方法描述和tag 之間需要插入空白註釋行。不需要每個參數param的描述都對齊,但要保證同個param的多行描述對齊。param 的描述不需要在句尾加標點。
/**
* 第一句話是這個方法的簡短摘要。
* 如果這個描述太長,記得換行。
*
* @param builderTest 添加參數的描述,如果描述很長,
* 需要回車,這裏需要對齊
* @param isTest 添加參數描述,不需要刻意與其他param
* 參數對齊
*/
public void test(String builderTest, boolean isTest){}
@return 是用來描述方法的返回值。要寫在@param tag之後,與其他tag 之間不需要換行。@throws 是對方法可能會拋出的異常來進行說明的,通常格式爲:異常類名+異常在方法中出現的原因。見下:
/**
* 第一句話是這個方法的簡短摘要。
*
* @param capacity 添加參數描述,不需要刻意與其他param
* 參數對齊
* @return 描述返回值的含義,可以多行,不需要句號結尾
* @throws IllegalArgumentException 如果初始容量爲負
* <ul>
* <li>這是拋出異常的條件1(非必須),注意<li>格式
* </ul>
* @throws 注意如果方法還存在其他異常,可並列多個
*/
public int test(int capacity){
if (capacity < 0)
throw new IllegalArgumentException("Illegal initial capacity");
return capacity;
}
@deprecated 用於指出一些舊特性已由改進的新特性所取代,建議用戶不要再使用舊特性。常與@link 配合,當然@link的使用位置沒有任何限制,當我們的描述需要涉及到其他類或方法時,我們就可以使用@link啦,javadoc會幫我們生成超鏈接:
/**
* 第一句話是這個方法的簡短摘要。
* 如果這個描述太長,記得換行。
*
* @deprecated 從2.0版本起不推薦使用,替換爲{@link #Test2()}
* @param isTest 添加參數描述,不需要刻意與其他param
* 參數對齊
*/
public void test(boolean isTest){}
@link 常見形式見下:
@code 用來標記一小段等寬字體,也可以用來標記某個類或方法,但不會生成超鏈接。常與@link配合,首次通過@link生成超鏈接,之後通過@code 呈現等寬字體。
/**
* 第一句話是這個方法的簡短摘要。
* 我們可以關聯{@link Test}類,隨後通過{@code Test}類怎樣怎樣
* 也可以標記一個方法{@code request()}
*
* @param isTest 添加參數描述,不需要刻意與其他param
* 參數對齊
*/
public void test(boolean isTest){}
@see 用來引用其它類的文檔,相當於超鏈接,javadoc會在其生成的HTML文件中,將@see標籤鏈到其他的文檔上:
/**
* 第一句話是這個方法的簡短摘要。
*
* @param capacity 添加參數描述,不需要刻意與其他param
* 參數對齊
* @return 描述返回值的含義,可以多行,不需要句號結尾
* @throws IllegalArgumentException 如果初始容量爲負
* @see com.te.Test2
* @see #test(int)
*/
public int test(int capacity){
if (capacity < 0)
throw new IllegalArgumentException("Illegal initial capacity");
return capacity;
}
@see形式與@link類似,見下:
@since 用來指定方法或類最早使用的版本。在標記類時,常與@version和@author配合,一個用來指定當前版本和版本的說明信息,一個用來指定編寫類的作者和聯繫信息等。我們也可以通過< pre>來添加一段代碼示例。見下:
/**
* 第一句話是這個類的簡短摘要。
* <pre>
* Test<Test2> t = new Test<>();
* </pre>
*
* <p>同樣可以多個段落。
*
* @param <T> 注意當類使用泛型時,我們需要使用params說明。這時格式需要插入空白行
*
* @author mjzuo [email protected]
* @see com.te.Test2
* @version 2.1
* @since 2.0
*/
public class Test<T extends Test2> {
/**
* 第一句話是這個方法的簡短摘要。
*
* @params capacity 參數的描述
* @return 返回值的描述
* @since 2.1
*/
public int test2(int capacity) {
return capacity;
}
}
@inheritDoc 用來從當前這個類的最直接的基類中繼承相關文檔到當前的文檔註釋中。如下的test() 方法,會直接繼承該類的直接父類的test()方法註釋。注意與其他tag 不需要插入空行:
/**
* {@inheritDoc}
* @since 2.0
*/
public void test(boolean isTest){}
@docRoot 它總是指向文檔的根目錄,表示從任何生成的頁面到生成的文檔根目錄的相對路徑。例如我們可以在每個生成的文檔頁面都加上版權鏈接,假設我們的版權頁面copyright.html 在根目錄下:
/**
* <a href="{@docRoot}/copyright.html">Copyright</a>
*/
public class Test {}