Java文檔註釋全攻略

註釋：註釋起到對代碼標註和解釋的做用，若是你去看看JDK源碼，會發現他們有許多的註釋，並且註釋是比代碼還要多的，可見爲代碼添加註釋是很是重要的，寫好註釋能讓別人更加容易看懂你的代碼，註釋能夠分爲如下三種。html

（一）單行註釋

使用//進行註釋：java

//阿平好帥

（二）多行註釋

使用/**/進行註釋：apache

/** 阿平是真的帥/

（三）文檔註釋

使用/** */進行註釋：微信

/** 
    阿平也太帥了吧
*/

文檔註釋主要是用來生成java開發文檔javadoc的，生成的開發文檔和Java自己的API幫助文檔是同樣的，也就是對你所寫的類進行解釋說明，因此它還須要搭配一些文檔標記，進行解釋說明，並且在文檔註釋中可使用HTML語言，jdk源碼中有大量的文檔註釋，因此弄懂文檔註釋能夠幫助你更好的看懂源碼。app

文檔註釋一般還會配合HTML標籤進行使用，比較經常使用的標籤有<p><pre>等標籤，p標籤用於表示段落，pre標籤可用於顯示計算機源碼。less

注意：pre標籤中若是有小於號、大於號、例如泛型在生產javadoc時會報錯。eclipse

一、文檔標記

（1）通用的文檔標記

如下文檔標記在類、方法、變量和常量上都常常使用。ide

@link：用於快速連接到相關代碼，使用格式：{@link 包名.類名#方法名(參數類型)}工具

// 徹底限定的類名
{@link java.util.Collections}

// 省略包名，只寫類名
{@link String}

// 省略類名，表示指向當前的某一個方法
{@link #toString()}

// 徹底限定方法名，包名.類名.方法名(參數類型)
{@link java.lang.String#charAt(int)}

@code：將文本標記爲代碼樣式文本，通常在Javadoc中只要涉及到類名或者方法名，都須要使用@code進行標記，使用格式：{@code text}，其會被解析爲<code> text </code>測試
```
//標記類名
{@code ArrayList}

//標記方法名
{@code isEmpty}

//標記某個代碼關鍵字
{@code null}
```

（2）類上經常使用文檔標記

@param：若是一個類支持泛型時，能夠經過@param來解釋泛型的類型
```
/**
  @param <E> the type of elements in this list  
*/
```

@author：用來標記做者，若是一段程序是由多個做者來維護，則能夠標記多個@author,@author 後面能夠跟做者姓名(也能夠附帶做者郵箱地址)、組織名稱(也能夠附帶組織官網地址)

// 純文本做者
@author Rod Johnson

// 純文本做者，郵件
@author Igor Hersht, igorh@ca.ibm.com

// 超連接郵件 純文本做者
@author <a href="mailto:ovidiu@cup.hp.com">Ovidiu Predescu</a>

// 純文本郵件
@author shane_curcuru@us.ibm.com

// 純文本 組織
@author Apache Software Foundation

// 超連接組織地址 純文本組織
@author <a href="https://jakarta.apache.org/turbine"> Apache Jakarta Turbine</a>

@see :另請參閱的意思，通常用於標記與本類相關聯的類，該標註能夠用在類或方法上。

/**
 * @see IntStream
 * @see LongStream
 * @see DoubleStream
 * @see <a href="package-summary.html">java.util.stream</a>
 * /

@since：表示從如下版本開始有這個類，標記文件建立時項目當時對應的版本，後面能夠跟版本號或是時間。

//跟版本號，如下是ArrayList類裏的標記，說明從jdk1.2開始就有該類了
/*
   * @since   1.2
**/
//跟時間
/**
* @since 20 April 2021
*/

@version：用於標記當前類版本，默認爲1.0
```
/**
 * @version 1.0
 */
```

以上是類上經常使用的文檔標註，類上的文檔格式以下：

概要描述：一般用一段話簡要的描述該類的基本內容。
詳細描述：一般用幾大段話詳細描述該類的功能與相關狀況。
文檔標註：用於標註該類的做者、時間、版本、參略等信息。

如下是String類的中文檔標註的事例：

/**
 * The {@code String} class represents character strings. All
 * string literals in Java programs, such as {@code "abc"}, are
 * implemented as instances of this class.
 * <p>
 * Strings are constant; their values cannot be changed after they
 * are created. String buffers support mutable strings.
 * Because String objects are immutable they can be shared. For example:
 * <blockquote><pre>
 *     String str = "abc";
 * </pre></blockquote><p>
 * is equivalent to:
 * <blockquote><pre>
 *     char data[] = {'a', 'b', 'c'};
 *     String str = new String(data);
 * </pre></blockquote><p>
 * Here are some more examples of how strings can be used:
 * <blockquote><pre>
 *     System.out.println("abc");
 *     String cde = "cde";
 *     System.out.println("abc" + cde);
 *     String c = "abc".substring(2,3);
 *     String d = cde.substring(1, 2);
 * </pre></blockquote>
 * <p>
 * The class {@code String} includes methods for examining
 * individual characters of the sequence, for comparing strings, for
 * searching strings, for extracting substrings, and for creating a
 * copy of a string with all characters translated to uppercase or to
 * lowercase. Case mapping is based on the Unicode Standard version
 * specified by the {@link java.lang.Character Character} class.
 * <p>
 * The Java language provides special support for the string
 * concatenation operator (&nbsp;+&nbsp;), and for conversion of
 * other objects to strings. For additional information on string
 * concatenation and conversion, see <i>The Java&trade; Language Specification</i>.
 *
 * <p> Unless otherwise noted, passing a {@code null} argument to a constructor
 * or method in this class will cause a {@link NullPointerException} to be
 * thrown.
 *
 * <p>A {@code String} represents a string in the UTF-16 format
 * in which <em>supplementary characters</em> are represented by <em>surrogate
 * pairs</em> (see the section <a href="Character.html#unicode">Unicode
 * Character Representations</a> in the {@code Character} class for
 * more information).
 * Index values refer to {@code char} code units, so a supplementary
 * character uses two positions in a {@code String}.
 * <p>The {@code String} class provides methods for dealing with
 * Unicode code points (i.e., characters), in addition to those for
 * dealing with Unicode code units (i.e., {@code char} values).
 *
 * <p>Unless otherwise noted, methods for comparing Strings do not take locale
 * into account.  The {@link java.text.Collator} class provides methods for
 * finer-grain, locale-sensitive String comparison.
 *
 * @implNote The implementation of the string concatenation operator is left to
 * the discretion of a Java compiler, as long as the compiler ultimately conforms
 * to <i>The Java&trade; Language Specification</i>. For example, the {@code javac} compiler
 * may implement the operator with {@code StringBuffer}, {@code StringBuilder},
 * or {@code java.lang.invoke.StringConcatFactory} depending on the JDK version. The
 * implementation of string conversion is typically through the method {@code toString},
 * defined by {@code Object} and inherited by all classes in Java.
 *
 * @author  Lee Boynton
 * @author  Arthur van Hoff
 * @author  Martin Buchholz
 * @author  Ulf Zibis
 * @see     java.lang.Object#toString()
 * @see     java.lang.StringBuffer
 * @see     java.lang.StringBuilder
 * @see     java.nio.charset.Charset
 * @since   1.0
 * @jls     15.18.1 String Concatenation Operator +
 */
public final class String
    implements java.io.Serializable, Comparable<String>, CharSequence {
}

（3）方法上經常使用文檔標記

@param：該文檔標記後面寫方法的參數名，再寫參數描述。

/**
* @param str 
* the {@code CharSequence} to check (may be {@code null})
*/
public static boolean containsWhitespace(@Nullable CharSequence str) {}

@return：該文檔標記後面寫返回值得描述。

/**
* @return {@code true} if the {@code String} is not {@code null}, its
*/
public static boolean hasText(@Nullable String str){}

@throws：該文檔標記後面寫異常的類型和異常的描述，用於描述該方法可能拋出的異常。

/**
* @throws IllegalArgumentException when the given source contains invalid encoded sequences
*/
public static String uriDecode(String source, Charset charset){}

@exception：該標註用於描述方法簽名throws對應的異常。

/**
* @exception IllegalArgumentException if <code>key</code> is null.
*/
public static Object get(String key) throws IllegalArgumentException {}

@see：可用在類與方法上，表示參考的類或方法。

/**
* @see java.net.URLDecoder#decode(String, String)
*/
public static String uriDecode(String source, Charset charset){}

以上是方法上經常使用的文檔標註，方法上的文檔格式以下：

概要描述：一般用一段話簡要的描述該方法的基本內容。
詳細描述：一般用幾大段話詳細描述該方法的功能與相關狀況。
文檔標註：用於標註該方法的參數、返回值、異常、參略等信息。

如下是String類中charAt方法的示例：

/**
     * Returns the {@code char} value at the
     * specified index. An index ranges from {@code 0} to
     * {@code length() - 1}. The first {@code char} value of the sequence
     * is at index {@code 0}, the next at index {@code 1},
     * and so on, as for array indexing.
     *
     * <p>If the {@code char} value specified by the index is a
     * <a href="Character.html#unicode">surrogate</a>, the surrogate
     * value is returned.
     *
     * @param      index   the index of the {@code char} value.
     * @return     the {@code char} value at the specified index of this string.
     *             The first {@code char} value is at index {@code 0}.
     * @exception  IndexOutOfBoundsException  if the {@code index}
     *             argument is negative or not less than the length of this
     *             string.
     */
    public char charAt(int index) {}

（4）變量和常量上的文檔規範

變量和常量上用的比較多的文檔標記是@link和@code，主要註釋該常量或變量的基本用法和相關內容。

如下是示例：

/**
     * The value is used for character storage.
     *
     * @implNote This field is trusted by the VM, and is a subject to
     * constant folding if String instance is constant. Overwriting this
     * field after construction will cause problems.
     *
     * Additionally, it is marked with {@link Stable} to trust the contents
     * of the array. No other facility in JDK provides this functionality (yet).
     * {@link Stable} is safe here, because value is never null.
     */
    private final byte[] value;

二、生成幫助文檔

首先先展現下我寫的文檔註釋代碼：

HelloWorld.java

package demo2;
/**
 * <p>這是一個測試javadoc的類
 * 
 * @author codepeace
 * @version 1.0
 * @since  1.8
 *
 */
public class HelloWorld {
	String name;
	
	/**
	 * 
	 * @param name
	 * @return name 
	 * @throws Exception
	 * {@code name} 
	 */
	public String test(String name)throws Exception{
		return name;
	}
}

Doc.java

package demo2;
/**
 * <p>這是一個測試javadoc的類
 * 
 * @author codepeace
 * @version 1.0
 * @since  1.8
 *
 */
public class Doc {
	String name;
	
	/**
	 * 
	 * @param name
	 * @return name 
	 * @throws Exception
	 * {@code name} 
	 */
	public String test(String name)throws Exception{
		return name;
	}
}

（1）使用命令行的方式

用wiodow打開cmd終端，而後進入要編譯的java文件目錄的路徑中，以下所示：

輸入命令：javadoc -encoding UTF-8 -charset UTF-8 *.java，就能將你的java文件編譯成幫助文檔。

-encoding 是編碼格式， -charset是字符集格式，須要查看你文件的編碼格式，能夠經過打開記事本查看編碼格式。

編譯成功後你後發現當前路徑下會多出不少文件，咱們須要的文件是index.html文件。

點開後爲以下樣式，至此幫助文檔生成完畢。

（2）使用IDE工具的方式

使用idea生成javadoc文檔

打開 idea，點擊 Tools-> Generate JavaDoc，這樣會打開生成 javadoc 文檔的配置頁面。

配置javadoc文檔輸出詳情：
1. 選擇要輸出文檔的範圍，選擇是整個項目仍是模塊仍是單個文件。
2. 文檔要輸出路徑。
3. 選擇哪些類型的方法或參數能夠生成文檔。
4. Locale 選擇地區，這個決定了文檔的語言，中文就是zh_CN。
5. 傳入JavaDoc的參數，通常寫 -encoding UTF-8 -charset UTF-8，表示編碼格式。

點擊肯定，運行無誤後，打開你所選擇的文檔輸出路徑後，選擇index.html，就是所輸出的javadoc文檔。

使用eclipse生成javadoc文檔

打開eclipse，點擊 Project-> Generate JavaDoc，這樣會打開生成 javadoc 文檔的配置頁面。

配置如下javadoc文檔輸出詳情，後點擊next
1. 選擇要輸出成文檔的文件或模塊
2. 選擇哪些類型的方法或參數能夠生成文檔
3. 文檔要輸出路徑。

設置文檔名後，點擊next

設置編碼格式通常寫-encoding UTF-8 -charset UTF-8，設置jre版本，而後點擊完成，在剛纔設置的輸出路徑中找到index.html便可。

注意點：eclipse的默認編碼不是UTF-8，因此要將其修改成UTF-8，修改方法以下：

打開eclipse，點擊 Window-> Preferences->Workspace，將默認的GBK編碼改成UTF-8便可。

更多精彩內容敬請關注微信公衆號：【平兄聊Java】