註釋:註釋起到對程式碼標註和解釋的作用,如果你去看看JDK原始碼,會發現他們有許多的註釋,而且註釋是比程式碼還要多的,可見為程式碼新增註釋是非常重要的,寫好註釋能讓別人更加容易看懂你的程式碼,註釋可以分為以下三種。
(一)單行註釋
使用//進行註釋:
//阿平好帥
(二)多行註釋
使用/**/進行註釋:
/** 阿平是真的帥/
(三)文件註釋
使用/** */進行註釋:
/**
阿平也太帥了吧
*/
文件註釋主要是用來生成java開發文件javadoc的,生成的開發文件和Java本身的API幫助文件是一樣的,也就是對你所寫的類進行解釋說明,所以它還需要搭配一些文件標記,進行解釋說明,而且在文件註釋中可以使用HTML語言,jdk原始碼中有大量的文件註釋,所以弄懂文件註釋可以幫助你更好的看懂原始碼。
文件註釋通常還會配合HTML標籤進行使用,比較常用的標籤有<p><pre>等標籤,p標籤用於表示段落,pre標籤可用於顯示計算機原始碼。
注意:pre標籤中如果有小於號、大於號、例如泛型 在生產javadoc時會報錯。
1、文件標記
(1)通用的文件標記
以下文件標記在類、方法、變數和常量上都經常使用。
-
@link: 用於快速連結到相關程式碼,使用格式:{@link 包名.類名#方法名(引數型別)}
// 完全限定的類名 {@link java.util.Collections} // 省略包名,只寫類名 {@link String} // 省略類名,表示指向當前的某一個方法 {@link #toString()} // 完全限定方法名,包名.類名.方法名(引數型別) {@link java.lang.String#charAt(int)}
-
@code: 將文字標記為程式碼樣式文字,一般在Javadoc中只要涉及到類名或者方法名,都需要使用@code進行標記,使用格式:{@code text},其會被解析為
text
//標記類名 {@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 ( + ), 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)方法上常用文件標記
-
@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;
2、生成幫助文件
首先先展示下我寫的文件註釋程式碼:
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文件輸出詳情:
- 選擇要輸出文件的範圍,選擇是整個專案還是模組還是單個檔案。
- 文件要輸出路徑。
- 選擇哪些型別的方法或引數可以生成文件。
- Locale 選擇地區,這個決定了文件的語言,中文就是zh_CN。
- 傳入JavaDoc的引數,一般寫
-encoding UTF-8 -charset UTF-8
,表示編碼格式。
- 點選確定,執行無誤後,開啟你所選擇的文件輸出路徑後,選擇index.html,就是所輸出的javadoc文件。
- 使用eclipse生成javadoc文件
- 開啟eclipse,點選 Project-> Generate JavaDoc,這樣會開啟生成 javadoc 文件的配置頁面。
- 配置以下javadoc文件輸出詳情,後點選next
- 選擇要輸出成文件的檔案或模組
- 選擇哪些型別的方法或引數可以生成文件
- 文件要輸出路徑。
- 設定文件名後,點選next
- 設定編碼格式 一般寫
-encoding UTF-8 -charset UTF-8
,設定jre版本,然後點選完成,在剛才設定的輸出路徑中找到index.html即可。
-
注意點:eclipse的預設編碼不是UTF-8,所以要將其修改為UTF-8,修改方法如下:
開啟eclipse,點選 Window-> Preferences->Workspace,將預設的GBK編碼改為UTF-8即可。
更多精彩內容敬請關注微信公眾號:【平兄聊Java】