Java的註釋說明

時間 2019-11-21

標籤 java 註釋說明欄目 Java 简体版

原文原文鏈接

在Java裏面主要有三種註釋：行註釋、段落註釋、文檔註釋css

　　1)行註釋：行註釋也成爲單行註釋，行註釋使用「//註釋文字」的格式來對某一行的代碼進行註釋或者加以說明html

public class LineCommentjava

{瀏覽器

//這是單行註釋的範例函數

public static void main(String args[])工具

{測試

//這只是一個單行註釋的例子ui

System.out.println("Single Line Comment");this

}.net

}

　　上邊代碼裏面//後邊的文字就是行註釋的一個例子

　　2)段註釋：段註釋也成爲多行註釋，一般是當說明文字比較長的時候的註釋方法

public class MultiCommont

{

*這是段註釋的一個簡單的例子

*這裏是函數入口main方法

public static void main(String args[])

{

System.out.println("Multi Lines Comments");

}

　　3)文檔註釋：文檔註釋是Java裏面的一個比較厲害的功能，它能夠用於註釋類、屬性、方法等說明，並且經過JDK工具javadoc直接生成相關文檔，文檔註釋的基本格式爲「/**...*/」，不只僅如此，文檔註釋自己還存在語法

　　[1]文檔和文檔註釋的格式化：

　　生成的文檔是HTML格式的，而這些HTML格式的標識符並非javadoc加的，而是咱們在寫註釋的時候寫上去的。所以在格式化文檔的時候須要適當地加入HTML標籤，例如：

/**

*This is first line.

*This is second line.

*This is third line.

**/

　　[2]文檔註釋的三部分：

　　根據在文檔中顯示的效果，文檔註釋能夠分爲三個部分，這裏舉個例子：

/**

*testDoc方法的簡單描述

*testDoc方法的詳細說明

*@param testInput String 打印輸入的字符串

*@return 沒有任何返回值

**/

public void testDoc(String testInput)

{

System.out.println(testInput);

}

　　簡述：文檔中，對於屬性和方法都是現有一個列表，而後纔在後面一個一個的詳細說明，列表中屬性名或者方法名後面那段說明都是簡述。

　　詳細說明：該部門對屬性或者方法進行了詳細說明，在格式上不須要特殊的要求，能夠寫成前邊講的HTML的格式，如同上邊第二行的內容。【*：這裏有個技巧就是簡述和詳細說明儘可能不要重複，在簡述中出現過的內容不須要在詳細說明中進行第二次描述，能夠理解爲詳細說明是簡述的一種擴展。後邊章節的概念說明代碼大部分我都沒有寫註釋，也請各位讀者見諒！】

　　特殊說明：除開上邊的兩部分，最後一個部分就是特殊說明部分，特殊說明部分使用JavaDoc標記進行，這些都是JavaDoc工具可以解析的特殊標記，這一點下邊章節將會講到

　　[3]使用javadoc標記：

　　javadoc標記是java插入文檔註釋中的特殊標記，它們用於識別代碼中的特殊引用。javadoc標記由「@」以及其後跟着的標記類型和專用註釋引用組成。它的格式包含了三個部分：

　　@、標記類型、專用註釋引用

　　有時候咱們也能夠直接理解爲兩個方面：@和標記類型、專用註釋引用；Javadoc工具能夠解析Java文檔註釋中嵌入的特殊標記，這些文檔標記能夠幫助自動從源代碼生成完整的格式化API，標記用「@」符號開頭，區分大小寫，必須按照正確的大小寫字母輸入。標記必須從一行的開頭開始，不然會被視爲普通文本，並且按照規定應將相同名字的標記放一塊兒，好比全部的@see標記應該放到一塊兒，接下來看一看每一種標記的含義。

　　@author(1.0)：語法[@author name-text]

　　當使用-author選項的時候，用指定的name-text在生成文檔的時候添加「Author」項，文檔註釋能夠包含多個@author標記，能夠對每一個@author指定一個或者多個名字。

　　@deprecated(1.0)：語法[@deprecated deprecated-text]

　　添加註釋，只是不該該再使用該API（儘管是可用的），Javadoc工具會將deprecated-text移動到描述前面，用斜體顯示，而且在它前邊添加粗體警告：「不鼓勵使用」。deprecated-text的首句至少應該告訴用戶何時開始不鼓勵使用該API以及使用什麼替代它。Javadoc僅將首句複製到概覽部分和索引中，後面的語句還可解釋爲何不鼓勵使用，應該還包括一個指向替代API的{@link}標記【1.2版本用法】

對於Javadoc 1.2，使用{@link}標記，這將在須要的地方建立內嵌連接，如：

/**

*@deprecated 在JDK X.X中，被{@link #methodName(paramList)}取代

**/

【*：在上邊的標記裏面X.X指代JDK的版本，後邊的連接連接的是方法的簽名，methodName爲方法名，paramList爲參數列表】

對於Javadoc 1.1，標準格式是爲每一個@deprecated標記建立@see標記（它不可內嵌）

　　@exception(1.0)：語法[@exception class-name description]

　　@throws(1.2)：語法[@throws class-name description]

　　以上兩個標記是同義詞，用class-name和description文本給生成的文檔添加「拋出」子標題，其中class-name是該方法可拋出的異常名。

　　{@link}(1.2)：語法[{@link name label}]

　　出入指向指定name的內嵌連接，該標記中name和label的語法與@see標記徹底相同，以下所述，可是產生的內嵌連接而不是在「參見」部分防止連接。該標記用花括號開始並用花括號結束，以使它區別於其餘內嵌文本，若是須要在標籤內使用「}」，直接使用HTML的實體表示法：}

　　@param(1.0)：語法[@param parameter-name description]

　　給「參見」部分添加參數，描述能夠繼續到下一行進行操做，主要是提供了一些參數的格式以及描述

　　@return(1.0)：語法[@return description]

　　用description本文添加「返回」部分，該文本應描述值的返回類型和允許範圍

　　@see(1.0)：語法[@see reference]

　　該標記是一個相對複雜的標記，添加「參見」標題，其中有指向reference的連接或者文本項，文檔註釋可包含任意數目的@see標記，它們都分組在相同的標題下，@see有三種格式：

@see 「string」注：該形式在JDK 1.2中沒有用，它不打印引用文本

爲string添加文本項，不產生連接，string是經過該URL不可用的書籍或者其餘信息引用，Javadoc經過查找第一個字符爲雙引號（"）的情形來區分它前邊的狀況，好比：

@see "這是Java教材，主要是提供給初學者"

上邊的註釋將會生成：

參見：

　　「這是Java教材，主要是提供給初學者」

@see <a href="page.html#section">Java某章節</a>

添加URL#value定義的連接，其中URL#value是相對URL或者絕對URL，JavaDoc工具經過查找第一個字符小寫符號（<）區分它與其餘狀況，好比：

@see <a href="page.html#section">測試規範</a>

上邊的註釋將會生成：

參見：

　　測試規範

@see package.class#member label【比較經常使用的一種格式】

添加帶可見文本label的連接，它指向Java語言中指定名字的文檔。其中label是可選的，若是省略，則名字做爲可見文本出現，並且嵌在<code>HTML標記中，當想要縮寫可見文本或不一樣於名字的可見文本的時候，可使用label。

——package.class#member是Java語言中的任何有效名字——包名、類名、接口名、構造函數名、方法名或域名——除了用hash字符(#)取代成員名前面的點以外，若是該名字位於帶文檔的類中，則Javadoc將自動建立到它的連接，要建立到外部的引用連接，可以使用-link選項，使用另外兩種@see形式中的任何一種引用不屬於引用類的名字的文檔。

——label是可選文本，它是連接的可見標籤，label可包含空白，若是省略label，則將顯示package.class.member，並相對於當前類和包適當縮短

——空格是package.class#member和label之間的分界符，括號內的空格不表示標籤的開始，所以在方法各參數之間可以使用空格

@see package.class#member的典型形式

引用當前類的成員

@see #field

@see #method(Type,Type,...)

@see #method(Type argname,Type argname,...)

引用當前包或導入包中的其餘類

@see Class#field

@see Class#method(Type,Type,...)

@see Class#method(Type argname,Type argname,...)

@see Class

引用其餘包（全限定）

@see package.Class#field

@see package.Class#method(Type,Type,...)

@see package.Class#method(Type argname,Type argname,...)

@see package.Class

@see package簡單說明一下：

——第一套形式（沒有類和包）將致使 Javadoc 僅搜索當前類層次。它將查找當前類或接口、其父類或超接口、或其包含類或接口的成員。它不會搜索當前包的其他部分或其餘包（搜索步驟 4-5）。

——若是任何方法或構造函數輸入爲不帶括號的名字，例如 getValue，且若是沒有具備相同名字的域，則 Javadoc 將正確建立到它的連接，可是將顯示警告信息，提示添加括號和參數。若是該方法被重載，則 Javadoc 將連接到它搜索到的第一個未指定方法。

——對於全部形式，內部類必須指定爲 outer.inner，而不是簡單的 inner。

——如上所述，hash 字符（#）而不是點（.）用於分隔類和成員。這使 Javadoc 可正確解析，由於點還用於分隔類、內部類、包和子包。當 hash 字符（#）是第一個字符時，它是絕對不可少的。可是，在其餘狀況下，Javadoc 一般不嚴格，並容許在不產生歧義時使用點號，可是它將顯示警告。

　　@see標記的搜索次序——JavaDoc將處理出如今源文件（.java）、包文件（package.html）或概述文件（overview.html）中的@see標記，在後兩種文件中，必須徹底限定使用@see提供的名字，在源文件中，可指定全限定或部分限定的名字，@see的搜索順序爲：

當前類或接口

任何包含類和接口，先搜索最近的

任何父類和超接口，先搜索最近的

當前包

任何導入包、類和接口，按導入語句的次序搜索

　　@since(1.1)：語法[@since since-text]

　　用since-text指定的內容給生成文檔添加「Since」標題，該文本沒有特殊內部結構，該標記表示該改變或功能自since-text所指定的軟件件版本後就存在了，例如：@since JDK 1.4

　　@serial(1.2)：語法[@serial field-description]

　　用於缺省的可序列化域的文檔註釋中，可選的field-description加強了文檔註釋對域的描述能力，該組合描述必須解釋該域的意義並列出可接受值，若是有須要描述能夠多行，應該對自Serializable類的最第一版本以後添加的每一個可序列化的域添加@since標記。

　　@serialField(1.2)：語法[@serialField field-name field-type field-description]

　　簡歷Serializable類的serialPersistentFields成員的ObjectStreamField組件的文檔，應該對每一個ObjectStreamField使用一個@serialField標記

　　@serialData(1.2)：語法[@serialData data-description]

　　data-description創建數據（尤爲是writeObject方法所寫入的可選數據和Externalizable.writeExternal方法寫入的所有數據）序列和類型的文檔，@serialData標記可用於writeObject、readObject、writeExternal和readExternal方法的文檔註釋中

　　@version(1.0)：語法[@version version-text]

　　當使用-version選項時用version-text指定的內容給生成文檔添加「版本」子標題，該文本沒有特殊內部結構，文檔註釋最多隻能包含一個@version標記。

　　{@code}(1.5)：語法[{@code text}]

該標籤等同於<code>{@literal}</code>，裏面能夠直接過濾掉HTML的標籤，能夠不用<和>來顯示（<和>），在這個代碼塊裏面的text部分，能夠直接書寫代碼，即便使用了Hello，在HTML裏面也不會識別成爲加粗的Hello，而仍是原來的代碼段Hello的格式輸出

　　{@docRoot}(1.3)：語法[{@docRoot}]

　　表明相對路徑生成的文件的（目標）的根從任何產生的網頁目錄，當您要包括如版權頁或公司徽標文件的時候它是有用的，你要引用所生成的網頁，連接從每一個頁面底部的版權頁面是常見的。（@docRoot將標記可用於在命令行，並在兩個文檔註釋：這個標記是有效的，在全部文檔註釋：概述、包裝類、接口、構造、方法和領域，包括任何標記文本的一部分（如@return ，@param和@deprecated的使用）。

　　好比：

/**

* See the <a href="{@docRoot}/copyright.html">Copyright</a>.

**/

　　{@inheritDoc}(1.4)：語法[{@inheritDoc}]

　　繼承（拷貝）文檔從最近的「繼承類或可執行的接口」到當前在這個標籤的位置的文檔註釋內容，這使您能夠編寫更多與繼承相關的通常性文檔

　　下邊的狀況比較適合：

在一個方法的主要描述塊，在這種狀況下，主要描述是整個繼承樹結構裏面的類和接口的一個拷貝。

在文本參數返回的@return @param和@throws等方法標記，在這種狀況下，文本標記是整個層次結構裏面標籤的拷貝。

　　{@linkplain}(1.4)：語法[{@linkplain package.class#member label}]

　　和{@link}相似，除非連接的label是用普通文本的格式顯示的，當文本是普通文本的時候該標籤就可以起做用，例如：

Refer to {@linkplain add() the overridden method}