Java 文檔注解最全詳解，建議收藏！

一、簡(jiǎn)介

在開發(fā)項(xiàng)目的時(shí)候，我們可能時(shí)不時(shí)需要查閱官方 JDK API 文檔，以便于更加清晰的了解某個(gè)類方法的用途以及正確的使用姿勢(shì)，比如關(guān)于 HashMap 類的介紹。

打開 JDK 源碼，你會(huì)看到代碼上有大量的文檔注釋，包括包的描述、類的描述、方法描述以及類屬性的描述說明等等，同時(shí)你還會(huì)驚奇的發(fā)現(xiàn)，源碼上的注釋與 JDK API 文檔中的描述如出一轍，以 HashMap 為例，類注釋描述如下！

實(shí)際上，JDK API 文檔是根據(jù) Javadoc 工具生成的！

那什么是 Javadoc 呢？

官方回答: Javadoc is a tool for generating API documentation in HTML format from doc comments in source code.

翻譯過來的意思是：Javadoc 是一款能根據(jù)源代碼中的文檔注釋來產(chǎn)生 HTML 格式的 API 文檔的工具。

簡(jiǎn)單的說就是，只要你在 java 源碼中按照標(biāo)準(zhǔn)的格式寫注釋，就可以利用 javadoc 這款工具自動(dòng)生成配套的 java API 文檔。

本篇文章的主要內(nèi)容，就是總結(jié) java 文檔注釋應(yīng)該按照什么樣的格式來寫，只要格式對(duì)了，java API 文檔就能按照工具來自動(dòng)生成。

二、文檔注釋格式總結(jié)

Java 文檔注釋是專門為了用 javadoc 工具自動(dòng)生成文檔而編寫的一套注釋標(biāo)準(zhǔn)，通過 javadoc 命令可以把文檔注釋中的內(nèi)容生成文檔，并輸出到 HTML 文件中，與一般的注釋有所不同，相關(guān)的規(guī)則如下：

• 所有的 Java 文檔注釋都以/**開頭，*/結(jié)尾，而不是/*或//
• 文檔注釋覆蓋范圍包括：類、接口、方法、構(gòu)造器、成員字段，如果寫在其他位置，比如函數(shù)內(nèi)部，被視為無效的文檔注釋
• 每個(gè) Java 文檔注釋都要和其后對(duì)應(yīng)的類/方法/字段/包保持同樣的縮進(jìn)
• Java 文檔注釋的內(nèi)容，支持采用HTML語(yǔ)法規(guī)則書寫，同時(shí)也支持一些額外的輔助標(biāo)簽

在類/方法上的文檔標(biāo)注一般分為三段，順序如下：

• 第一段：概要描述，通常用一句話或者一段話簡(jiǎn)要描述該類的作用，以英文句號(hào)結(jié)束，這句話會(huì)被提取并放到索引目錄中
• 第二段：詳細(xì)描述，通常用一段話或者多段話詳細(xì)描述該類的作用，每段話都以英文句號(hào)結(jié)束，詳細(xì)描述中可以使用 html 標(biāo)簽，如<p>，<pre>，<a>，<li>等標(biāo)簽
• 第三段：文檔標(biāo)記，通常用于標(biāo)注作者、創(chuàng)建時(shí)間、參閱類等信息，描述部分和文檔標(biāo)記之間必須空一行

比如java.util.Arrays類和部分方法，源碼 java 文檔注釋如下！

package java.util;

/**
 * This class contains various methods for manipulating arrays (such as
 * sorting and searching). This class also contains a static factory
 * that allows arrays to be viewed as lists.
 *
 * <p>The documentation for the methods contained in this class includes
 * briefs description of the <i>implementations</i>. Such descriptions should
 * be regarded as <i>implementation notes</i>, rather than parts of the
 * <i>specification</i>. Implementors should feel free to substitute other
 * algorithms, so long as the specification itself is adhered to. (For
 * example, the algorithm used by {@code sort(Object[])} does not have to be
 * a MergeSort, but it does have to be <i>stable</i>.)
 *
 * <p>This class is a member of the
 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
 * Java Collections Framework</a>.
 *
 * @author Josh Bloch
 * @author Neal Gafter
 * @author John Rose
 * @since  1.2
 */
public class Arrays {
 
    /**
     * Sorts the specified array into ascending numerical order.
     *
     * <p>Implementation note: The sorting algorithm is a Dual-Pivot Quicksort
     * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
     * offers O(n log(n)) performance on many data sets that cause other
     * quicksorts to degrade to quadratic performance, and is typically
     * faster than traditional (one-pivot) Quicksort implementations.
     *
     * @param a the array to be sorted
     */
    public static void sort(int[] a) {
        DualPivotQuicksort.sort(a, 0, a.length - 1, null, 0, 0);
    }
}

三、文檔標(biāo)簽總結(jié)

Javadoc 工具可以識(shí)別文檔注釋中的一些特殊標(biāo)簽，這些標(biāo)簽一般以@開頭，后跟一個(gè)指定的名字，有的也以{@開頭，以}結(jié)束，javadoc 可以識(shí)別的標(biāo)簽如下！

• @author

說明：用于指明作者或者組織，可以附加郵箱或者超鏈接，如果有多少個(gè)作者就用多少個(gè)該標(biāo)簽。適用范圍：包、 類、接口 案例如下：

/**
 * @author xxxx
 * @author [email protected]
 * @author <a href="mailto:[email protected]">xxxxx</a>
 */

• @since

說明：用于指明最早出現(xiàn)在哪個(gè)版本，可填版本號(hào)或日期，有時(shí)也可表明可運(yùn)行的JDK版本。適用范圍：包、類、接口、方法、成員屬性、構(gòu)造器 案例如下：

/**
 * @since 1.4
 * @since 15 April 2001
 * @since JDK1.5
 */

• @version

說明：用于指明當(dāng)前版本號(hào)。適用范圍：包、 類、接口 案例如下：

/**
 * @version 1.8.3.4
 */

• @code

說明：用于將一些關(guān)鍵字或代碼解析成代碼樣式。適用范圍：包、類、接口、方法、成員屬性、構(gòu)造器 案例如下：

/**
 * xxxx,{@code int var = 1;}xxxx
 */

• @return

說明：對(duì)函數(shù)返回值的注釋。適用范圍：方法 案例如下：

/**
 * @return <code>true</code> 執(zhí)行成功;<code>false</code> 執(zhí)行失敗.
 */

• @param

說明：用于方法的入?yún)⒚懊枋鲂畔ⅰ＿m用范圍：構(gòu)造器、方法 案例如下：

/**
 * @param img the image to be drawn
 */

• @value

說明：只能用于對(duì)常量進(jìn)行注釋，該標(biāo)簽常用于寫在字段上的 Javadoc 注釋。適用范圍：方法、成員屬性 案例如下：

/**
 * Default start value. {@value #START_VALUE}
 */

• @throws 和 @exception

說明：用戶描述構(gòu)造函數(shù)或方法所會(huì)拋出的異常。適用范圍：方法、構(gòu)造器 案例如下：

/**
 * @throws IllegalArgumentException
 *         if {@code fromIndex > toIndex}
 */

• @link 、@linkplain 和 @see

說明：用于創(chuàng)建一個(gè)超鏈接到相關(guān)代碼。適用范圍：包、類、接口、方法、成員屬性、構(gòu)造器 注意事項(xiàng)：1、@link 和 @linkplain的區(qū)別在于：@link直接將將超鏈接中的地址當(dāng)作顯示的文本，其格式為 {@link 地址}；而 @linkplain可以自行設(shè)定顯示的文本，其格式為{@link 地址 顯示文本}，三個(gè)字段用空格隔開。2、@link 和 @see的區(qū)別在于：@link可以放在某一行中的任意位置；而 @see必須放在某一行中的最開始。

案例如下：

/**
 * xxx {@link java.lang.String#charAt(int)}
 * xxx {@link #sort(Object[])}
 * xxx {@linkplain Comparable natural ordering}
 * @see #deepHashCode(Object[])
 */

• @inheritDoc

說明：用于繼承父類的 javadoc 注釋，父類的文檔注釋會(huì)被拷貝到子類。適用范圍：方法 案例如下：

/**
 * {@inheritDoc}
 * <p>
 * The speed of tiger will be returned.
 * 
 * @return the speed of tiger 
 */

• @deprecated

說明：告訴用戶該 API 已過時(shí)，并且已被哪些新的 API 取代了。用@see或 @link指向新的API。該舊的 API 之所以不刪掉，通常是為了兼容性考慮。。適用范圍：包、類、接口、方法、成員屬性、構(gòu)造器 案例如下：

/**
* @deprecated As of JDK 1.1, replaced by 
* {@link #setBounds(int, int, int, int)}
*/

• @serial

說明：說明一個(gè)序列化屬性。適用范圍：方法、成員屬性 案例如下：

/**
 * @serial description
 */

• @serialData

說明：用于說明通過 writeObject() 和 writeExternal() 方法寫的數(shù)據(jù)。。適用范圍：方法、成員屬性 案例如下：

/**
 * @serialData description
 */

• @serialField

說明：用于說明一個(gè) ObjectStreamField 組件。適用范圍：方法、成員屬性 案例如下：

/**
 * @serialField name type description
 */

最后，在使用文檔注釋時(shí)，通常會(huì)按照如下順序進(jìn)行使用。

• @author
• @version
• @param
• @return
• @exception / @throws
• @see
• @since
• @serial / @serialField / @serialData
• @deprecated

三、java api 文檔生成方式

Javadoc 是 Sun 公司提供的一個(gè)技術(shù)，它從程序源代碼中抽取類、方法、成員等注釋，然后形成一個(gè)和源代碼配套的 API 幫助文檔。

文檔的創(chuàng)建命令如下：

javadoc -d 文檔存放目錄 -author -version 源文件名.java

這條命令編譯一個(gè)名為源文件名.java的 java 源文件，并將生成的文檔存放在文檔存放目錄指定的目錄下，生成的文檔中index.html就是文檔的首頁(yè)。

-author和-version兩個(gè)選項(xiàng)可選項(xiàng)，使用者可以通過javadoc -help命令查看 javadoc 使用說明。

注意：Javadoc 默認(rèn)只提取 public、protected 修飾的部分，如果要提取 private 修飾的部分，需要使用 -private。

下面是一個(gè)使用說明文檔注釋的簡(jiǎn)單實(shí)例。

/**
 * 這個(gè)類演示了文檔注釋
 *
 * @author Ayan Amhed
 * @version 1.2
 */
public class SquareNum {
    /**
     * This method returns the square of num.
     * This is a multiline description. You can use
     * as many lines as you like.
     *
     * @param num The value to be squared.
     * @return num squared.
     */
    public double square(double num) {
        return num * num;
    }

    /**
     * This method inputs a number from the user.
     *
     * @return The value input as a double.
     * @throws IOException On input error.
     * @see IOException
     */
    public double getNumber() throws IOException {
        InputStreamReader isr = new InputStreamReader(System.in);
        BufferedReader inData = new BufferedReader(isr);
        String str;
        str = inData.readLine();
        return (new Double(str)).doubleValue();
    }

    /**
     * This method demonstrates square().
     *
     * @param args Unused.
     * @return Nothing.
     * @throws IOException On input error.
     * @see IOException
     */
    public static void main(String args[]) throws IOException {
        SquareNum ob = new SquareNum();
        double val;
        System.out.println("Enter value to be squared: ");
        val = ob.getNumber();
        val = ob.square(val);
        System.out.println("Squared value is " + val);
    }
}

使用 javadoc 工具處理 SquareNum.java 文件，生成 javadoc api 文檔，在命令行輸入如下命令，即可實(shí)現(xiàn)文檔的生成！

javadoc SquareNum.java

四、小結(jié)

Javadoc 是一款為程序生成 API 文檔的工具，只需按照規(guī)定的格式編寫代碼文檔注釋，即可生成 API 的幫助文檔。

本文主要圍繞 java 文檔標(biāo)簽的使用進(jìn)行介紹，如果有錯(cuò)誤的地方，歡迎網(wǎng)友留言指出！

五、參考

1、javadoc 官方文檔

2、博客園 - 小白都看得懂的Javadoc使用教程

3、菜鳥教程 - Java 文檔注釋