JAVADOC注釋詳解__JAVA

java注釋的分類

    1、單行注釋：int SUM = 100; //這是一個單行注釋

    2、多行注釋：

    /*

     *這是一個多行注釋
     */

    3、文檔注釋：

    /**

     *這是一個文檔注釋

     * @return a

     */

java注釋和文檔注釋

    作為一個java程式員我們一定都喜歡看官方的開發文檔，文檔中很詳細的包括了類和介面參數方法等資訊，並提供了許多類之間的關係等等。java的開發文檔是由HTML頁面進行展示的，但是用了很久我們才知道，這些文檔實際上不是一點一點的寫出來的，我們自己也可以進行產生。

    安裝了 JDK 之後，安裝目錄下有一個 src.jar 檔案或者 src.zip 檔案，它們都是以 ZIP 格式壓縮的，可以使用 WinZip 解壓。解壓之後，我們就可以看到分目錄放的全是 .java 檔案。是了，這些就是 Java 運行類的源碼了，非常完整，連注釋都寫得一清二楚，我們可以對比這裡的注釋和開發文檔，以java.util.List為例：這是官網API截圖

    接下來再看一下源碼資訊：

package java.util;

/**
 * An ordered collection (also known as a <i>sequence</i>).  The user of this
 * interface has precise control over where in the list each element is
 * inserted.  The user can access elements by their integer index (position in
 * the list), and search for elements in the list.<p>
 *
 * Unlike sets, lists typically allow duplicate elements.  More formally,
 * lists typically allow pairs of elements <tt>e1</tt> and <tt>e2</tt>
 * such that <tt>e1.equals(e2)</tt>, and they typically allow multiple
 * null elements if they allow null elements at all.  It is not inconceivable
 * that someone might wish to implement a list that prohibits duplicates, by
 * throwing runtime exceptions when the user attempts to insert them, but we
 * expect this usage to be rare.<p>
 *
 * The <tt>List</tt> interface places additional stipulations, beyond those
 * specified in the <tt>Collection</tt> interface, on the contracts of the
 * <tt>iterator</tt>, <tt>add</tt>, <tt>remove</tt>, <tt>equals</tt>, and
 * <tt>hashCode</tt> methods.  Declarations for other inherited methods are
 * also included here for convenience.<p>

.....

 * @param <E> the type of elements in this list
 *
 * @author  Josh Bloch
 * @author  Neal Gafter
 * @see Collection
 * @see Set
 * @see ArrayList
 * @see LinkedList
 * @see Vector
 * @see Arrays#asList(Object[])
 * @see Collections#nCopies(int, Object)
 * @see Collections#EMPTY_LIST
 * @see AbstractList
 * @see AbstractSequentialList
 * @since 1.2
 */

public interface List<E> extends Collection<E> {

.....

}

    可以看出來，java的開發文檔其實就是在將代碼中的注釋按照相應的規則整理出來的，這對程式的閱讀者和使用者十分關鍵，由此可見，學會寫注釋對於一個程式員來說是十分關鍵的，也能體現一個程式員的水平。 文檔和文檔注釋的格式

    文檔注釋可以用在類，方法，屬性上進行說明。文檔內部要注意細節問題。

    文檔的產生格式是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.

    *注意，文檔說明後面需要緊跟類、介面、方法或屬性 文檔注釋的三個組成部分 

   

    第一個部分作為類、介面、方法、屬性的簡述。簡述在文檔注釋的最前面，簡述的末尾需要加上一個點號“.”，就是使用點號來分割文檔注釋，有的時候點號會出現錯誤，我們就用<p>作為第二部分的開頭進行分割。

    第二部分就是注釋的詳細部分，對屬性或方法等進行詳細的說明，在格式上沒有什麼特殊的要求。

    第三部分是特殊說明部分，這個部分包括聲明作者、版本說明、參數說明、參考說明、傳回值說明。拋出異常說明等，這一部分最好和第二部分有一個空行，不然可能會出現錯誤。 

常用的javadoc標記及其使用

    1、@see的使用：

    @see的句法有三種

      ①、@see 類名

      類名可以根據需要唯寫出類名，如String，或者寫出全名：java.lang.String，但需要注意的是，在用類名的時候需要這個java源檔案中import這個類，否則只能用全名。

      ②、@see#方法名或屬性名稱

      如果是屬性名稱，則只需要寫出屬性名稱即可，如果是方法名，則需要寫出方法名以及參數類型，如果沒有參數，也需要寫出一對括弧。

      如：@see #contains(Object)、@see #count()、@see number

      ③、@see 類名#方法名或屬性名稱

      如：@see Object#equals(Object)、@see java.lang.String#toString()

    2、@author、@version的使用：

    這兩個標記分別指明作者和版本號碼，預設情況下javadoc自動將其忽略，但命令列開關-author和-version可以修改個功能，使其包含的資訊流輸出，這兩個標記都可以多個使用，但是版本號碼只有第一個出現的有效。

    3、@param、@return和@exception的使用：

    這三個標記只能用於方法，@param描述參數，@return描述傳回值，@exception描述拋出異常，用法如下：

      ①、@param 參數名 參數說明

      每一個@param都只能描述一個方法的參數，可以多次使用。

      ②、@return 傳回值說明

      一個方法只能使用一個@return，如果有多個，javadoc會發出警告，並且只有第一個聲明的有效。

      @exception 異常類名 異常說明

      @exception可以多次使用，並且異常的類名需要注意在java原檔案中是否有匯入，如果沒有需要寫類全名。

      如：

    /**
     * test 方法的簡述，這個方法用於做javadoc的測試.
     * <p> test方法的詳細說明，這裡是詳細說明的第一行<br>
     * test方法詳細說明的第二行
     * 
     * @param a firstnum
     * @param b lastnum
     * @exception java.lang.ArithmeticException throw when b is 0
     * @return 傳回值為a/b
     */
    public int test(int a,int b) throws java.lang.ArithmeticException{
        return a/b;
    }

      *注意：寫文檔注釋的時候應該注意正確的匹配參數，javadoc在一定程度上不會檢查我們寫的文檔注釋，如果寫錯誤可能會造成一些困惑
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可以給定包列表進行編譯，如：javadoc xcg xcg.test    

    也可以給出源檔案清單，如：javadoc xcg/test/JavaDocTest.java

    以上兩種方式的編譯結果不同，用包列表產生的文檔被架構分成了三個部分：包列表、類列表和類說明

    在eclipse或myeclipse中可以使用file->Export->javadoc可以進行手動輸出javadoc，需要注意產生的時候可能會出現錯誤: 編碼GBK的不可映射字元，這時就需要在流程的最後一步加上一句話控制字元：-encoding UTF-8 -charset UTF-8，如：

注釋規範

    1、注釋原則：

      ①注釋形式統一

      ②注釋內容準確簡單

    2、注釋條件：

      ①基本注釋（必須加）：類、介面的注釋、建構函式的注釋、方法的注釋、全域變數的注釋、欄位/屬性的注釋

      ②特殊必須加的注釋：典型演算法、代碼不清晰易懂時加註釋、修改代碼時需要加註釋、在迴圈分支需要加註釋、為他人提供的介面等資訊必須加註釋。