前言

之前有寫過一篇 Java 註解的介紹。 參考以上鍊接。

雖然註解、註釋只相差一個字，但是用法就差異很大。

總體一句話， 註解給編譯器看， 註釋是給人看的。

基於此的話， 對於一個方法來說：

1. 把這個方法的作用， 輸入，輸出描述清楚就可以了，更多的可以加上一些作者呀，版本呀這樣一些資訊

2. 註釋編排的美觀一些

做到這兩點應該就可以了。 舉個例子：

	/*******************************************************************************
	* NAME:			usage
	* DESCRIPTION:	XXX
	* ARGUMENTS:	N/A
	* RETURN:       
	* AUTHOR: 		oscar999
	* VERSION:      V0.1
	*******************************************************************************/
 

看上去這是一個不錯的註釋^^.

但是對於Java 語言來說， 註釋被賦予了更多的功能。 就是你可以使用javadoc 這個功能把程式碼中的註釋匯出到  html 的檔案中。

如果你的程式碼是共用性很高的程式碼的話， 這份文件就是一份API的參考文件， 類似Java API.

所以， 要產生出這樣的文件，就要遵循java 定義的一些註釋規範， 才能產生出規範的文件出來。

Java 類方法的標準註釋

還是從類的方法的註釋說起。

    /**
     * Read a line of text.  A line is considered to be terminated by any one
     * of a line feed ('\n'), a carriage return ('\r'), or a carriage return
     * followed immediately by a linefeed.
     *
     * @param      ignoreLF1  If true, the next '\n' will be skipped
 

     * @param      ignoreLF2  If true, the next '\n' will be skipped

 * * @return A String containing the contents of the line, not including * any line-termination characters, or null if the end of the * stream has been reached * * @see java.io.LineNumberReader#readLine() * * @exception IOException If an I/O error occurs */
（不去關注以上註釋的意義，只關注其定義的樣式）

1. 首先看最上面的 “Read a line of text.  A line .. ” 這一段是對這個方法的一些描述。

第一個句號前面的部分， 也就是 “Read a line of text.” 會出現在 “方法摘要” 中

全部的描述資訊 會出現在“ 方法詳細資訊” 中

2. @param 定義的是方法的輸入引數，（可以新增多個）出現在“ 方法詳細資訊” 中。（引數和引數描述之間使用空格隔開， 在產生的文件中轉成了  -）

3. @return  返回值的描述

4. @see  參考的描述

5. @exception 異常丟擲的描述

美觀考慮， 不同類的標籤可以換一行顯示， 比如 @param 和 @return 直接空一行。

Java 類標準註釋

類的註釋和方法註釋的格式基本相同。 區別的地方：

1. 放置的位置不同。 類的註釋放在類定義的上面， 方法的註釋放在方法定義的上面。

2. 類的註釋比較會使用   @version  @author  @since 這樣的標籤。

看模板

/** will buffer the input from the specified file.  Without buffering, each
* invocation of read() or readLine() could cause bytes to be read from the
* file, converted into characters, and then returned, which can be very
* inefficient. 
* 
* 
* Test Description
* 
* <p> Programs that use DataInputStreams for textual input can be localized by
* replacing each DataInputStream with an appropriate BufferedReader.
*
* @see FileReader
* @see InputStreamReader
*
* @version 	0.1, 11/20/13
* @author	oscar999
* @since	JDK1.5
*/

doc 中顯示的效果是：

同樣， 描述的第一句出現在“類概要”中。

類的詳細資訊顯示如下：

值得注意的是 description 中<p> 的使用。 如果沒有加<p> , 在java code 中不管是否有換行，產生的doc 中都不換行。 加上<p> 的話， doc 中出現換行。

補充

補充一下， 產生javadoc的方法：

1. 命名行方式：  javadoc  + 引數

2. 使用Eclipse IDE 匯出

如果在Eclipse IDE 中， 在原始檔或是專案上右鍵單擊 , 選 Export  --->

Java --> Javadoc 就可以產生了。