/** * This button looks like this: * <img src="doc-files/Button.gif"> */
在Java中，提供了3種注釋方式：短（單行）注釋、塊（多行）注釋及文檔注釋。單行和多行注釋很容易理解，將注釋符之間的內容當做注釋，在編譯和運行時將這部分內容忽略。下面介紹單行注釋和多行注釋的方法。
（1）單行注釋：單行注釋就是在程序中注釋一行代碼。
注釋規則：在代碼中單起一行注釋， 注釋前最好有一行空行，並與其后的代碼具有一樣的縮進層級。如果單行無法完成，則應采用塊注釋。
注釋格式：
// 注釋內容
（2）多行注釋：一次將程序中的多行注釋掉。
注釋規則：注釋若干行，通常用於提供文件、方法、數據結構等的意義與用途的說明，或者算法的描述。一般位於一個文件或者一個方法的前面，起到引導的作用，也可以根據需要放在合適的位置。
注釋格式：
/* 注釋內容 */
來看一個單行注釋和多行注釋的例子。
源文件：MessageComment.java
//這是一個單行注釋 /* 這是一個 多行注釋 */
1 public class MessageComment { 2 3 public static void main(String[] args) { 4 5 System.out.println("發信息"); 6 7 // System.out.println("此條信息不會顯示"); 8 9 } 10 11 }
在Java中，比較特殊的是javadoc注釋，包含在這部分中的注釋可以通過javadoc命令來自動生成API文檔。通過javadoc工具，可以保證程序代碼和技術文檔的同步。在修改了程序中的注釋后，只需要通過javadoc，就可以方便地生成相應的技術文檔。
我們知道，在軟件開發過程中，文檔編寫的重要性不亞於程序代碼本身。如果代碼與文檔是分離的，那么在每次修改代碼時，都需要修改相應的文檔就會是一件很麻煩的事情。 所以通過javadoc將代碼同文檔“連接”起來。在Java中，還有一種特別的注釋方式：文檔注釋。利用這種注釋，可以從Java源文件中提取這些注釋的內容，來產生HTML格式的API文檔。
文檔注釋的基本格式如下：
/** 文檔注釋內容 */
注意把文檔注釋和多行注釋區分清楚，文檔注釋的開始標記是“/**”，而多行注釋標記的開始標記是“/*”。
由於文檔注釋最重要的一個功能就是用它來生成HTML格式的API文檔，因此，很多用於HTML格式化的HTML標記也可以用在文檔注釋中，在從這些注釋中提取注釋生成HTML文件的時候，在生成的HTML文件中，將使用這些HTML標記來格式化HTML文件內容。常用的HTML標記有<b>…</b>、<code>…</code>等。關於這些HTML標記及其他的HTML標記，請讀者參考相關的HTML資料。
和多行注釋不同的另一個地方是，文檔注釋並不是可以放在Java代碼的任何地方，javadoc工具在從Java代碼中提取注釋生成API文檔時，主要從以下幾項內容中提取信息。
·包。
·公有（public）類與接口。
·公有方法和受保護（protected）方法。
·公有屬性和受保護屬性。
因此，文檔注釋也應該放到相應的位置中。
1．文檔注釋位置
（1）類注釋。類注釋用於說明整個類的功能、特性等，它應該放在所有的“import”語句之后，在class定義之前。
這個規則也適用於接口（interface）注釋。
（2）方法注釋。方法注釋用來說明方法的定義，比如，方法的參數、返回值及說明方法的作用等。方法注釋應該放在它所描述的方法定義前面。
（3）屬性注釋。默認情況下，javadoc只對公有（public）屬性和受保護屬性（protected）產生文檔——通常是靜態常量。
（4）包注釋。類、方法、屬性的注釋都直接放到Java的源文件中，而對於包的注釋，無法放到Java文件中去，只能通過在包對應的目錄中添加一個package.html的文件來達到這個目的。當生成HTML文件時，package.html文件的<BODY>和</BODY>部分的內容將會被提取出來當做包的說明。關於包注釋，后面還會有更進一步的解釋。
（5）概要注釋。除了包注釋外，還有一種類型的文檔無法從Java源文件中提取，就是對所有類文件提供概要說明的文件。同樣的，也可以為這類注釋單獨新建一個HTML文件，這個文件的名字為“overview.html”，它的<BODY>和</BODY>標記之間的內容都會被提取。
2．javadoc標記
在javadoc注釋中，常用@來表示一個javadoc標記，常用的javadoc標記如下：
·@author：作者。
·@version：版本。
·@docroot：表示產生文檔的根路徑。
·@deprecated：不推薦使用的方法。
·@param：方法的參數類型。
·@return：方法的返回類型。
·@see：用於指定參考的內容。
·@exception：拋出的異常。
·@throws：拋出的異常，和exception同義。
需要注意這些標記的使用是有位置限制的。其中可以出現在類或者接口文檔注釋中的標記有：@see、@deprecated、@author、@version等。
可以出現在方法或者構造器文檔注釋中的標記有：@see、@deprecated、@param、@return、@throws、@exception等。
可以出現在屬性文檔注釋中的有：@see、@deprecated等。
3．javadoc命令語法
javadoc的命令行語法如下：
javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]
參數可以按照任意順序排列。下面對這些參數作一些說明。
（1）packagenames 包列表：這個選項可以是一系列的包名（用空格隔開），例如，java.lang java.lang.reflect java.awt。因為javadoc不遞歸作用於子包，不允許對包名使用通配符；所以必須顯式地列出希望建立文檔的每一個包。
（2）sourcefiles 源文件列表。這個選項可以是一系列的源文件名（用空格隔開），可以使用通配符。javadoc允許4種源文件：類源代碼文件、包描述文件、總體概述文件、其他雜文件。
·類源代碼文件：類或者接口的源代碼文件。
·包描述文件：每一個包都可以有自己的包描述文件。包描述文件的名稱必須是 “package.html”，與包的.java文件放置在一起。包描述文件的內容通常是使用HTML標記寫的文檔。javadoc執行時將自動尋找包描述文件。如果找到，javadoc將首先對描述文件中<body></body>之間的內容進行處理，然后把處理結果放到該包的Package Summary頁面中，最后把包描述文件的第一句（緊靠<body>）放到輸出的Overview Summary頁面中，並在語句前面加上該包的包名。
總體概述文件：javadoc可以創建一個總體概述文件描述整個應用或者所有包。總體概述文件可以被任意命名，也可以放置到任意位置。-overview選項可以指示總體概述文件的路徑和名稱。總體概述文件的內容是使用HTML標記寫的文檔。javadoc在執行的時候，如果發現-overview選項，那么它將首先對文件中<body></body>之間的內容進行處理；然后把處理后的結果放到輸出的Overview Summary 頁面的底部；最后把總體概述文件中的第一句放到輸出的Overview Summary頁面的頂部。
其他雜文件：這些文件通常是指與javadoc輸出的HTML文件相關的一些圖片文件、Java源代碼文件（.java）、Java程序（.class）、Java小程序（Applets）、HTML文件。這些文件必須放在doc-files目錄中。每一個包都可以有自己的doc-files目錄。例如，你希望在java.awt.Button的HTML文檔中使用一幅按鈕的圖片（Button.gif）。首先，必須把圖片文件放到java\awt\doc-files\中；然后在Button.java文件中加入以下注釋：
files 包含文件。為了簡化javadoc命令，可以把需要建立文檔的文件名和包名放在一個或多個文本文件中。例如，為了簡化以下命令：
javadoc -d apidoc com.oristand.college com.oristand.school
可以建立一個名稱為mypackage.txt的文件，其內容如下：
com.oristand.college com.oristand.school
然后執行以下命令即可：
javadoc -d apidoc @mypackage.txt
·options 命令行選項。
① public 只顯示公共類及成員。
② protected 只顯示受保護的和公共的類及成員。默認選項。
③ package只顯示包、受保護的和公共的類及成員。
④ private 顯示所有類和成員。
-classpath classpathlist 指定javadoc查找“引用類”的路徑。引用類是指帶文檔的類加上它們引用的任何類。javadoc將搜索指定路徑的所有子目錄，classpathlist可以包含多個路徑（使用“;”隔開）。
一切就緒后，就可以使用JDK中的“javadoc”工具來生成相關的API文檔了。