image
image
image
image
注釋：注釋起到對(duì)代碼標(biāo)注和解釋的作用步绸，如果你去看看JDK源碼拳话，會(huì)發(fā)現(xiàn)他們有許多的注釋?zhuān)易⑨屖潜却a還要多的珍剑，可見(jiàn)為代碼添加注釋是非常重要的钓辆，寫(xiě)好注釋能讓別人更加容易看懂你的代碼缕溉，注釋可以分為以下三種考传。
（一）單行注釋
使用//進(jìn)行注釋?zhuān)?/p>
//阿平好帥
（二）多行注釋
使用/**/進(jìn)行注釋?zhuān)?/p>
/** 阿平是真的帥/
image
image
image
（三）文檔注釋
使用/** */進(jìn)行注釋?zhuān)?/p>
/**
阿平也太帥了吧
*/
文檔注釋主要是用來(lái)生成java開(kāi)發(fā)文檔javadoc的，生成的開(kāi)發(fā)文檔和Java本身的API幫助文檔是一樣的证鸥，也就是對(duì)你所寫(xiě)的類(lèi)進(jìn)行解釋說(shuō)明僚楞，所以它還需要搭配一些文檔標(biāo)記，進(jìn)行解釋說(shuō)明敌土，而且在文檔注釋中可以使用HTML語(yǔ)言镜硕，jdk源碼中有大量的文檔注釋?zhuān)耘臋n注釋可以幫助你更好的看懂源碼。
文檔注釋通常還會(huì)配合HTML標(biāo)簽進(jìn)行使用返干，比較常用的標(biāo)簽有<p><pre>等標(biāo)簽兴枯，p標(biāo)簽用于表示段落，pre標(biāo)簽可用于顯示計(jì)算機(jī)源碼矩欠。
注意：pre標(biāo)簽中如果有小于號(hào)财剖、大于號(hào)、例如泛型 在生產(chǎn)javadoc時(shí)會(huì)報(bào)錯(cuò)癌淮。
1躺坟、文檔標(biāo)記
（1）通用的文檔標(biāo)記
以下文檔標(biāo)記在類(lèi)、方法乳蓄、變量和常量上都經(jīng)常使用咪橙。
-
@link： 用于快速鏈接到相關(guān)代碼，使用格式：{@link 包名.類(lèi)名#方法名(參數(shù)類(lèi)型)}
// 完全限定的類(lèi)名 {@link java.util.Collections} // 省略包名，只寫(xiě)類(lèi)名 {@link String} // 省略類(lèi)名美侦，表示指向當(dāng)前的某一個(gè)方法 {@link #toString()} // 完全限定方法名产舞，包名.類(lèi)名.方法名(參數(shù)類(lèi)型) {@link java.lang.String#charAt(int)} -
@code： 將文本標(biāo)記為代碼樣式文本，一般在Javadoc中只要涉及到類(lèi)名或者方法名菠剩，都需要使用@code進(jìn)行標(biāo)記易猫，使用格式：{@code text}，其會(huì)被解析為<code> text </code>
//標(biāo)記類(lèi)名 {@code ArrayList} //標(biāo)記方法名 {@code isEmpty} //標(biāo)記某個(gè)代碼關(guān)鍵字 {@code null}
（2）類(lèi)上常用文檔標(biāo)記
-
@param：如果一個(gè)類(lèi)支持泛型時(shí)具壮，可以通過(guò)@param來(lái)解釋泛型的類(lèi)型
/** @param <E> the type of elements in this list */
-
@author：用來(lái)標(biāo)記作者准颓，如果一段程序是由多個(gè)作者來(lái)維護(hù)，則可以標(biāo)記多個(gè)@author,@author 后面可以跟作者姓名(也可以附帶作者郵箱地址)棺妓、組織名稱(chēng)(也可以附帶組織官網(wǎng)地址)
// 純文本作者 @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 > Apache Jakarta Turbine</a>
-
@see :另請(qǐng)參閱的意思，一般用于標(biāo)記與本類(lèi)相關(guān)聯(lián)的類(lèi)涧郊，該標(biāo)注可以用在類(lèi)或方法上贯被。
/** * @see IntStream * @see LongStream * @see DoubleStream * @see <a href="package-summary.html">java.util.stream</a> * / -
@since：表示從以下版本開(kāi)始有這個(gè)類(lèi)眼五，標(biāo)記文件創(chuàng)建時(shí)項(xiàng)目當(dāng)時(shí)對(duì)應(yīng)的版本妆艘，后面可以跟版本號(hào)或是時(shí)間。
//跟版本號(hào)看幼，以下是ArrayList類(lèi)里的標(biāo)記批旺，說(shuō)明從jdk1.2開(kāi)始就有該類(lèi)了 /* * @since 1.2 **/ //跟時(shí)間 /** * @since 20 April 2021 */ -
@version：用于標(biāo)記當(dāng)前類(lèi)版本，默認(rèn)為1.0
/** * @version 1.0 */
以上是類(lèi)上常用的文檔標(biāo)注诵姜，類(lèi)上的文檔格式如下：
- 概要描述：通常用一段話(huà)簡(jiǎn)要的描述該類(lèi)的基本內(nèi)容汽煮。
- 詳細(xì)描述：通常用幾大段話(huà)詳細(xì)描述該類(lèi)的功能與相關(guān)情況。
- 文檔標(biāo)注：用于標(biāo)注該類(lèi)的作者棚唆、時(shí)間暇赤、版本、參略等信息宵凌。
以下是String類(lèi)的中文檔標(biāo)注的事例：
/**
* 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 ( + ), and for conversion of
* other objects to strings. For additional information on string
* concatenation and conversion, see <i>The Java™ 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™ 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）方法上常用文檔標(biāo)記
-
@param：該文檔標(biāo)記后面寫(xiě)方法的參數(shù)名鞋囊，再寫(xiě)參數(shù)描述。
/** * @param str * the {@code CharSequence} to check (may be {@code null}) */ public static boolean containsWhitespace(@Nullable CharSequence str) {} -
@return：該文檔標(biāo)記后面寫(xiě)返回值得描述瞎惫。
/** * @return {@code true} if the {@code String} is not {@code null}, its */ public static boolean hasText(@Nullable String str){} -
@throws：該文檔標(biāo)記后面寫(xiě)異常的類(lèi)型和異常的描述溜腐，用于描述該方法可能拋出的異常。
/** * @throws IllegalArgumentException when the given source contains invalid encoded sequences */ public static String uriDecode(String source, Charset charset){} -
@exception：該標(biāo)注用于描述方法簽名throws對(duì)應(yīng)的異常瓜喇。
/** * @exception IllegalArgumentException if <code>key</code> is null. */ public static Object get(String key) throws IllegalArgumentException {} -
@see：可用在類(lèi)與方法上挺益，表示參考的類(lèi)或方法。
/** * @see java.net.URLDecoder#decode(String, String) */ public static String uriDecode(String source, Charset charset){}
以上是方法上常用的文檔標(biāo)注乘寒，方法上的文檔格式如下：
- 概要描述：通常用一段話(huà)簡(jiǎn)要的描述該方法的基本內(nèi)容望众。
- 詳細(xì)描述：通常用幾大段話(huà)詳細(xì)描述該方法的功能與相關(guān)情況。
- 文檔標(biāo)注：用于標(biāo)注該方法的參數(shù)、返回值烂翰、異常叉袍、參略等信息。
以下是String類(lèi)中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）變量和常量上的文檔規(guī)范
變量和常量上用的比較多的文檔標(biāo)記是@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;
image
2、生成幫助文檔
首先先展示下我寫(xiě)的文檔注釋代碼：
HelloWorld.java
package demo2;
/**
* <p>這是一個(gè)測(cè)試javadoc的類(lèi)
*
* @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>這是一個(gè)測(cè)試javadoc的類(lèi)
*
* @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打開(kāi)cmd終端棵里，然后進(jìn)入要編譯的java文件目錄的路徑中润文，如下所示：
image
- 輸入命令：
javadoc -encoding UTF-8 -charset UTF-8 *.java，就能將你的java文件編譯成幫助文檔殿怜。
-
-encoding是編碼格式典蝌，-charset是字符集格式，需要查看你文件的編碼格式头谜，可以通過(guò)打開(kāi)記事本查看編碼格式骏掀。
image
image
- 編譯成功后你后發(fā)現(xiàn)當(dāng)前路徑下會(huì)多出很多文件，我們需要的文件是index.html文件柱告。
image
- 點(diǎn)開(kāi)后為如下樣式怀浆，至此幫助文檔生成完畢辜妓。
image
（2）使用IDE工具的方式
- 使用idea生成javadoc文檔
- 打開(kāi) idea，點(diǎn)擊 Tools-> Generate JavaDoc，這樣會(huì)打開(kāi)生成 javadoc 文檔的配置頁(yè)面绊率。
image
- 配置javadoc文檔輸出詳情：
- 選擇要輸出文檔的范圍促脉，選擇是整個(gè)項(xiàng)目還是模塊還是單個(gè)文件助币。
- 文檔要輸出路徑猴蹂。
- 選擇哪些類(lèi)型的方法或參數(shù)可以生成文檔。
- Locale 選擇地區(qū)窒所，這個(gè)決定了文檔的語(yǔ)言鹉勒，中文就是zh_CN。
- 傳入JavaDoc的參數(shù)吵取，一般寫(xiě)
-encoding UTF-8 -charset UTF-8禽额，表示編碼格式。
image
- 點(diǎn)擊確定海渊，運(yùn)行無(wú)誤后绵疲，打開(kāi)你所選擇的文檔輸出路徑后，選擇index.html臣疑，就是所輸出的javadoc文檔盔憨。
image
image
- 使用eclipse生成javadoc文檔
- 打開(kāi)eclipse，點(diǎn)擊 Project-> Generate JavaDoc讯沈，這樣會(huì)打開(kāi)生成 javadoc 文檔的配置頁(yè)面郁岩。
image
- 配置以下javadoc文檔輸出詳情婿奔，后點(diǎn)擊next
- 選擇要輸出成文檔的文件或模塊
- 選擇哪些類(lèi)型的方法或參數(shù)可以生成文檔
- 文檔要輸出路徑。
image
- 設(shè)置文檔名后问慎，點(diǎn)擊next
image
- 設(shè)置編碼格式 一般寫(xiě)
-encoding UTF-8 -charset UTF-8萍摊，設(shè)置jre版本，然后點(diǎn)擊完成如叼，在剛才設(shè)置的輸出路徑中找到index.html即可冰木。
image
-
注意點(diǎn)：eclipse的默認(rèn)編碼不是UTF-8，所以要將其修改為UTF-8笼恰，修改方法如下：
打開(kāi)eclipse踊沸，點(diǎn)擊 Window-> Preferences->Workspace，將默認(rèn)的GBK編碼改為UTF-8即可社证。
image
image
image
image
image
更多精彩內(nèi)容敬請(qǐng)關(guān)注微信公眾號(hào)：【平兄聊Java】
