程式師世界 >> 編程語言 >> JAVA編程 >> JAVA綜合教程 >> 《瘋狂Java講義(第3版)》.(李剛)——注釋

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

編輯：JAVA綜合教程

《瘋狂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_16
Building 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;
    }
}