《瘋狂Java講義(第3版)》.(李剛)——注釋

《瘋狂Java講義(第3版)》.(李剛)——注釋

1、注釋的必要性：
1）自己或他人重構系統時方便理清楚這段代碼的流程和思路。
2）增加自己代碼的可讀性。
3）當代碼出現錯誤時注釋代碼可逐漸排查錯誤，縮小錯誤範圍（我自己更喜歡debug）。
2、注釋類型
1）單行注釋。
在需要注釋的前方加上雙斜杠即可（//）

    public class LineComment{    //這是單行注釋的範例    public static void main(String args[])    {        //這隻是一個單行注釋的例子        System.out.println("Single Line Comment");    }}

2）多行注釋。
在需要注釋的前方加上“/*”表示注釋開始，結尾加上“*/”表示注釋結束。
代碼：

    public class MultiCommont{    /*     *這是段注釋的一個簡單的例子     *這裡是函數入口main方法     */    public static void main(String args[])    {        System.out.println("Multi Lines Comments");    }}

3）文檔注釋。
文檔注釋是Java裡面的一個比較厲害的功能，它可以用於注釋類、屬性、方法等說明，而且通過JDK工具javadoc直接產生相關文檔，文檔注釋的基本格式為“/**...*/”，不僅僅如此，文檔注釋本身還存在文法
javadocTest:包括類、方法、成員變數的注釋

package com.alex.demo01;/** * Description *  * This is a demo of javadoc *  *  *   * @author Alex * @version 1.0 */public class JavaDocTest {    /**     * 簡單測試成員變數     */    private String name;    /**     * 主方法，程式的入口     * @param args     */    public static void main(String[] args) {        System.out.println("Hello World!");    }}

Test類:

package com.alex.demo01;/** * Description *  * This is a demo of javadoc *  *  *   * @author Alex * @version 1.0 */public class Test {    /**     * 簡單的成員變數     */    private int age;    /**     * Test的測試構造器     */    public Test(){    }}

javadoc 命令生產api文檔：

javadoc -d *Test.java

參數詳解：在windows命令列輸入javaodc -help

為了生產更詳細的api文檔，可以使用如下的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); }

　　簡述：文檔中，對於屬性和方法都是現有一個列表，然後才在後面一個一個的詳細說明，列表中屬性名稱或者方法名後面那段說明都是簡述。
　　
　　特殊說明：除開上邊的兩部分，最後一個部分就是特殊說明部分，特殊說明部分使用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 Java某章節

添加URL#value定義的連結，其中URL#value是相對URL或者絕對URL，JavaDoc工具通過尋找第一個字元小寫符號（<）區分它與其他情況，比如：

@see 測試規範

上邊的注釋將會產生：
參見：
　　測試規範
@see package.class#member label【比較常用的一種格式】
添加帶可見文本label的連結，它指向Java語言中指定名字的文檔。其中label是可選的，如果省略，則名字作為可見文本出現，而且嵌在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}]
　　該標籤等同於{@literal}，裡面可以直接過濾掉HTML的標籤，可以不用<和>來顯示（<和>），在這個代碼塊裡面的text部分，可以直接書寫代碼，即使使用了Hello，在HTML裡面也不會識別成為加粗的Hello，而還是原來的程式碼片段Hello的格式輸出
　　{@docRoot}(1.3)：文法[{@docRoot}]
　　代表相對路徑產生的檔案的（目標）的根從任何產生的網頁目錄，當您要包括如著作權頁或公司徽標檔案的時候它是有用的，你要引用所產生的網頁，連結從每個頁面底部的著作權頁面是常見的。（@docRoot將標記可用於在命令列，並在兩個文檔注釋：這個標記是有效，在所有文檔注釋：概述、封裝類、介面、構造、方法和領域，包括任何標記文本的一部分（如@return ，@param和@deprecated的使用）。
　　比如：

/**  * See the Copyright.  **/

　　{@inheritDoc}(1.4)：文法[{@inheritDoc}]
　　繼承（拷貝）文檔從最近的“繼承類或可執行檔介面”到當前在這個標籤的位置的文檔注釋內容，這使您可以編寫更多與繼承相關的一般性文檔
　　下邊的情況比較適合：
在一個方法的主要描述塊，在這種情況下，主要描述是整個繼承樹結構裡面的類和介面的一個拷貝。
在文本參數返回的@return @param和@throws等方法標記，在這種情況下，文本標記是整個階層裡面標籤的拷貝。
　　{@linkplain}(1.4)：文法[{@linkplain package.class#member label}]
　　和{@link}類似，除非連結的label是用普通文本的格式顯示的，當文本是普通文本的時候該標籤就能夠起作用，例如：

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

　　這個會顯示成：
Refer to the overridden method
　　{@value}(1.4)：文法[{@value package.class#field}]
　　主要用來顯示靜態欄位的值：

/** * The value of this constant is {@value} **/public static final String SCRIPT_START = "script";

　　[4]JavaDoc標記的舉例：
　　——[$]一個使用JavaDoc標記的例子——

/** * @author Lang Yu * @version 1.2 */public class JavaDocBasic {    /**     * @see "Main Function JavaDoc"     * @since JDK 1.4     * @param args The params of console     **/    public static void main(String args[]){        System.out.println("Hello World!");    }}

　　例如有這樣一小段代碼，在我機器上我放在了D:\Source\work下，然後進入該目錄下，使用下邊的命令：

D:\Source\work>javadoc -d doc JavaDocBasic.java

　　通過這樣的命令使用，在執行該命令了過後電腦上有下邊這樣的輸出，而且去目錄下邊可以看到一個doc檔案夾，用瀏覽器開啟裡面的index.html就可以看到產生的文檔的內容：
　　

Loading source file JavaDocBasic.java...Constructing Javadoc information...Standard Doclet version 1.6.0_16Building tree for all the packages and classes...Generating doc\JavaDocBasic.html...Generating doc\package-frame.html...Generating doc\package-summary.html...Generating doc\package-tree.html...Generating doc\constant-values.html...Building index for all the packages and classes...Generating doc\overview-tree.html...Generating doc\index-all.html...Generating doc\deprecated-list.html...Building index for all classes...Generating doc\allclasses-frame.html...Generating doc\allclasses-noframe.html...Generating doc\index.html...Generating doc\help-doc.html...Generating doc\stylesheet.css...

　　——[$]一個使用{@link}的例子——

/** * @author Lang Yu * @see java.lang.String */public class JavaDocLink {    private int a;    private int b;    /**     * {@link #getAdd() getAdd()} Method     * @return the result of (a + b)     **/    public int getAdd(){        return a + b;    }}