Java中怎么實現(xiàn)文檔注釋

Java中怎么實現(xiàn)文檔注釋，相信很多沒有經(jīng)驗的人對此束手無策，為此本文總結(jié)了問題出現(xiàn)的原因和解決方法，通過這篇文章希望你能解決這個問題。

網(wǎng)站建設(shè)哪家好，找創(chuàng)新互聯(lián)公司！專注于網(wǎng)頁設(shè)計、網(wǎng)站建設(shè)、微信開發(fā)、小程序開發(fā)、集團企業(yè)網(wǎng)站建設(shè)等服務(wù)項目。為回饋新老客戶創(chuàng)新互聯(lián)還提供了固原免費建站歡迎大家使用！

（一）單行注釋

使用//進行注釋：

//阿平好帥

（二）多行注釋

使用/**/進行注釋：

/** 阿平是真的帥/

（三）文檔注釋

使用/** */進行注釋：

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

文檔注釋主要是用來生成java開發(fā)文檔javadoc的，生成的開發(fā)文檔和Java本身的API幫助文檔是一樣的，也就是對你所寫的類進行解釋說明，所以它還需要搭配一些文檔標記，進行解釋說明，而且在文檔注釋中可以使用HTML語言，jdk源碼中有大量的文檔注釋，所以弄懂文檔注釋可以幫助你更好的看懂源碼。

文檔注釋通常還會配合HTML標簽進行使用，比較常用的標簽有

等標簽，p標簽用于表示段落，pre標簽可用于顯示計算機源碼。

注意：pre標簽中如果有小于號、大于號、例如泛型在生產(chǎn)javadoc時會報錯。

1、文檔標記

（1）通用的文檔標記

以下文檔標記在類、方法、變量和常量上都經(jīng)常使用。

@link：用于快速鏈接到相關(guān)代碼，使用格式：{@link 包名.類名#方法名(參數(shù)類型)}

// 完全限定的類名
{@link java.util.Collections}

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

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

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

@code：將文本標記為代碼樣式文本，一般在Javadoc中只要涉及到類名或者方法名，都需要使用@code進行標記，使用格式：{@code text}，其會被解析為 text
```
//標記類名
{@code ArrayList}

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

//標記某個代碼關(guān)鍵字
{@code null}
```

（2）類上常用文檔標記

@param：如果一個類支持泛型時，可以通過@param來解釋泛型的類型
```
/**
  @param  the type of elements in this list  
*/
```

@author：用來標記作者，如果一段程序是由多個作者來維護，則可以標記多個@author,@author 后面可以跟作者姓名(也可以附帶作者郵箱地址)、組織名稱(也可以附帶組織官網(wǎng)地址)

// 純文本作者
@author Rod Johnson

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

// 超鏈接郵件 純文本作者
@author Ovidiu Predescu

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

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

// 超鏈接組織地址 純文本組織
@author  Apache Jakarta Turbine

@see :另請參閱的意思，一般用于標記與本類相關(guān)聯(lián)的類，該標注可以用在類或方法上。
```
/**
 * @see IntStream
 * @see LongStream
 * @see DoubleStream
 * @see java.util.stream
 * /
```

@since：表示從以下版本開始有這個類，標記文件創(chuàng)建時項目當時對應(yīng)的版本，后面可以跟版本號或是時間。

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

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

以上是類上常用的文檔標注，類上的文檔格式如下：

概要描述：通常用一段話簡要的描述該類的基本內(nèi)容。
詳細描述：通常用幾大段話詳細描述該類的功能與相關(guān)情況。
文檔標注：用于標注該類的作者、時間、版本、參略等信息。

以下是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. *

* 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: *

 *     String str = "abc";
 *

* is equivalent to: *

 *     char data[] = {'a', 'b', 'c'};
 *     String str = new String(data);
 *

* Here are some more examples of how strings can be used: *

 *     System.out.println("abc");
 *     String cde = "cde";
 *     System.out.println("abc" + cde);
 *     String c = "abc".substring(2,3);
 *     String d = cde.substring(1, 2);
 *

* 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. *

* The Java language provides special support for the string * concatenation operator ( + ), and for conversion of * other objects to strings. For additional information on string * concatenation and conversion, see The Java™ Language Specification. * *

Unless otherwise noted, passing a {@code null} argument to a constructor * or method in this class will cause a {@link NullPointerException} to be * thrown. * *

A {@code String} represents a string in the UTF-16 format * in which supplementary characters are represented by surrogate * pairs (see the section Unicode * Character Representations 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}. *

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). * *

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 The Java™ Language Specification. 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, CharSequence { }

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

@param：該文檔標記后面寫方法的參數(shù)名，再寫參數(shù)描述。

/**
* @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對應(yīng)的異常。

/**
* @exception IllegalArgumentException if key 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){}

以上是方法上常用的文檔標注，方法上的文檔格式如下：

概要描述：通常用一段話簡要的描述該方法的基本內(nèi)容。
詳細描述：通常用幾大段話詳細描述該方法的功能與相關(guān)情況。
文檔標注：用于標注該方法的參數(shù)、返回值、異常、參略等信息。

以下是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.
     *
     * If the {@code char} value specified by the index is a
     * surrogate, 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）變量和常量上的文檔規(guī)范

變量和常量上用的比較多的文檔標記是@link和@code，主要注釋該常量或變量的基本用法和相關(guān)內(nèi)容。

以下是示例：

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

Java中怎么實現(xiàn)文檔注釋

2、生成幫助文檔

首先先展示下我寫的文檔注釋代碼：

HelloWorld.java

package demo2;
/**
 * 這是一個測試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;
/**
 * 這是一個測試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;
	}
}