Java-Notes Documents

 1.注釋：編譯時間, /*和*/之間的所有東西都會被忽略. 在連續注釋內容的每一行都以一個*開頭.

2.注釋文檔：將代碼和文檔放到同一個檔案中有利於二者的統一管理, 這就需要特殊的注釋文法和一個提取注釋的工具.

提取注釋的工具：javadoc, 尋找程式中的特殊注釋標籤, 解析由這些標籤標記的資訊, 同時將毗鄰注釋的類名or方法名提取出來.
javadoc輸出的是一個html檔案. 有個javadoc, 就有了建立文檔的標準.

注釋文法：javadoc只能在/**和*/注釋中出現. 使用javadoc的方式有兩種(1)嵌入html (2)使用"文檔標籤".
獨立文檔標籤：以"@"字元開頭的命令, 且要置於注釋行的最前面.
行內文檔標籤：以"@"字元開頭的命令, 可以出現在javadoc注釋中的任何地方, 但要括在花括弧內.
共有三種類型的注釋文檔, 分別對應於注釋位置後面的三種元素: 類, 變數, 方法. 即: 類注釋正好位於類定義之前; 變數注釋正好位於變數定義之前; 方法注釋正好位於方法定義之前.

javadoc只能為public和protect成員進行文檔注釋, private和包內可訪問成員的注釋會被忽略. 因為只有public和protect成員才能在檔案之外被使用. 至於所有對類所作的注釋, 則都會包含在輸出結果中.

嵌入式html：主要目的是為了對代碼及注釋進行格式化.
在文檔注釋中, 位於每一行開頭的星號和前置空格都會被javadoc丟棄. javadoc會對所有內容重新格式化, 使其與標準的文檔外觀一致. 不要在嵌入式html中使用標題標籤, 例如<hl><hr>, 因為javadoc會插入自己的標題, 而你的標題可能同它們發生衝突.

javadoc標籤樣本
@version標籤
格式：@version version-information
如果javadoc命令列使用了"-version"標記, 那麼就從產生的html文檔中提取出版本資訊(即version-information).

@author標籤
格式：@author author-information
如果javadoc命令列使用了"-author"標記, 那麼就從產生的html文檔中提取出作者資訊(即author-information).
可以使用多個標籤, 以便列出所有作者, 但是它們必須連續放置. 全部作者資訊會合并到同一段落, 置於產生的html中.

@param標籤
格式：@param parameter-name description 該標籤用於方法文檔中.

@return標籤
格式：@return description 該標籤用於方法文檔中.

@throws標籤
格式：@throws fully-qualified-class-name description
fully-qualified-class-name給出一個異常類的無歧義的名字. description告訴你為什麼此異常類會在方法調用中出現.

//: c02:HelloDate.java
import java.util.*;

/** *//**
 * Title: HelloDate類<br>
 * Description: 通過HelloDate類來說明java文檔注釋<br>
 * Description: Display a String and today's date<br>
 * Copyright: (c) 2008 Forest He<br>
 * Company: 群碩<br>
 * @author Bruce Eckel
 * @author www.BruceEckel.com
 * @version 2.0
 */
public class HelloDate...{
    /** *//**
     * Sole entry point to class & application
     * @param args array of String arguments
     * @return No return value
     * @exception No exceptions thrown
     */
    public static void main(String[] args) ...{
        System.out.println("Hello, it's: ");
        System.out.println(new Date());
    }
}///:~

第一行採用自己獨特的方法, 用一個":"作為特殊記號說明這是包含源檔案名稱的注釋行. 該行包含檔案的路徑資訊(c02代表第2章), 隨後是檔案名稱. 最後一行的注釋"///:~"標誌原始碼清單的結束.

編碼風格：類名的首字母要大寫; 如果類名由幾個單詞構成, 那麼把它們並在一起(即不要用底線來分隔名字), 其中每個內部單詞的首字母都採用大寫形式.
這種風格稱為"駝峰風格". 其他所有內容(方法, 成員變數, 對象引用名稱等), 公認的風格與類的風格一樣, 只是標識符的第一個字母要小寫.