Javadoc註解格式

在Java中只要按照標準的格式去寫註解，就能用Javadoc tool來自動產生出HTML格式的說明文件。在此提供Javadoc的註解格式。

※由於Javadoc產生後為HTML格式的文件，因此文件中需要美工或圖片、連結的功能可以直接以HTML標籤加入。

Javadoc的標準註解格式為：

/**
* 註解第一行
* 註解詳細內容
* .........
*
*@tag
*/

若註解只有單行，可以用這種形式(類別或實體變數常使用這種形式)：

/** 註解第一行 */

Javadoc tool能夠辨認的註解為類別、建構子、方法及成員的註解，因此Javadoc的註解區塊必須放置在上述幾種程式組成單位的起點前，上述組成單位的內部實作程式碼的註解將會被自動忽略，因此在類別、方法的註解中必須將內部實作的大略細節描述詳細，例如在java.util.arrays.sort(int[] a)的註解中，便詳細註明了所使用的演算法。類別也應該將其主要角色與必須知道的細節內容
請參考Java API Arrays類別中的 sort方法 ：http://java.sun.com/j2se/1.5.0/docs/api/java/util/Arrays.html

Javadoc tool會將註解(無論是類別、建構子、方法、成員)的第一行視為是整段註解的結論，因此第一行註解必須以簡短的方式說明描述對象的功能以及應該注意的事項。Javadoc tool會判定句點後跟著空白、tab或換行字元的字串為一行，因此若在第一行中使用句點卻不希望被判定為換行的情況下，
可以用HTML的註解標籤<!-- -->或HTML空白字元&nbsp; 讓句號的下一個字元不是空白或tab。
詳情可參考：http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#descriptions

在註解的描述中，可以使用Javadoc tool認得的tag來標示某些屬性，幫助Javadoc tool排版或產生連結。tag以@開頭，緊接著是tag name，最後是參數。。

類別或介面註解能夠使用的tag如下：

• @see
  稱為see also，有3種格式，如下:
  
  1. @see "字串"
     例如輸入:
     @see "The Java Programming Language"
     會產生:
     See Also:
     "The Java Programming Language"
  
  
  2. @see <a href="網址">顯示文字</a> (HTML連結)
     例如輸入:
     @see <a href="http://www.blogger.com/spec.html#section">Java Spec</a>
     會產生:
     See Also:
     Java Spec
  
  
  3. @see package.class#member label (最常用的一種)
     例如在註解裡輸入:
     /**
     * @see String#equals(Object) equals
     */
     會產生以下格式的HTML：
     <dl>
     <dt><b>See Also:</b>
     <dd><a href="../../java/lang/String#equals(java.lang.Object)"><code>equals</code></a>
     </dl>
     亦即，會產生連結到其他類別成員超連結。
     ※若是要連結到同一類別的成員，#號前的類別名稱可省略。
     ※若是要連結到同一包裝內的成員，類別前的包裝名稱可省略，如上述例子。
     ※注意若要連結到建構子或方法，參數型態必須寫好，參數名稱可省略。
     
  
  
• @author
  作者署名，用法是直接在標籤後接名字，例如：
  - @author 嘴砲安
  
  
• @since
  該類別加入時，軟體的版本。後面加上字串或數字就行了，例如：
  - @since 1.1
  

建構子或方法註解能夠使用的tag如下：

• @see
  詳見如上。
  


• @param
  方法或泛型的參數介紹。格式為 @param 參數名 參數說明。例如：
  /**
  * @param string 要被轉換的字串
  * @param type 要轉換成的型態
  * @param <T> 元素的型態
  * @param <V> 元素的值
  */
  <T, V extends T> V convert(String string, Class<T> type) {
  }
  ※類別的泛型參數也能夠使用此tag。
  


• @return
  方法的回傳值。後面接回傳值的敘述即可，例如：
  - @return 以參數id為根據取出的商品，當找不到商品時則為null。
  ※在特殊情況下回傳的值(像null)，必須註明。
  ※一個方法只有一個@return。
  
  
• @throws
  方法所丟出的例外。後面接丟出的例外類型，以及會丟出例外的情況，例如：
  -@throws IOException 如果網路發生異常，或者無法取得需要的檔案。
  ※受檢例外一定要寫說明，否則就算沒有寫出該例外，Javadoc tool還是會產生無說明的@throws項目。若方法有覆寫(overriding)父類別的方法，才可以不寫受檢例外的說明，Javadoc會直接從父類別的@throws拷貝說明。
  
  

類別變數或實體變數註解能夠使用的tag如下：

• @see
  詳見如上。
  


• {@value}
  可以連結到類別裡final static變數的值。這是使用這註解內文的tag，格式為：
  - {@value package.class#field}
  例如：
  /**
  * The value of this constant is {@value}
  */
  public static final String SCRIPT_START = "<script>"
  
  /**
  * Evaluates the script starting with {@value #SCRIPT_START}.
  */
  public String evalScript(String script) {
  }
  ※{@value #SCRIPT_START}會被替換為 <script>
  

一些可以用在內文裡的tag：

• {@link}
  產生到所在類別或其他類別之欄位、類別或方法的連結。格式為：
  - {@link package.class#member 顯示文字}
  例如如果要連結到同一類別的getComponentAt(int, int)方法，可以輸入：
  {@link #getComponentAt(int, int) getComponentAt}
  就會產生顯示文字是getComponentAt的連結，連結到同一類別裡的getComponentAt(int, int)的說明。
  


• {@linkplain}
  跟@link的用途一樣，只是字型是用plain text。
  


• {@inheritDoc}
  直接從最相近的父類別複製說明，複製的說明會顯示在tag放置的位置上。注意這個tag只能用在方法的註解內文、方法的@return、@param、@throws說明裡。
  ※注意如果覆寫父類別的方法卻沒有寫註解，Javadoc tool會直接複製父類別的說明。
  


• {@literal}
  自動處理特殊文字。格式為 {@literal 文字} 。可以把像角括號或其他會被HTML視為特殊字元的文字處理成一般文字。
  


• {@code}
  把文字以plain text的字體顯示出。格式為 {@code 文字}
  通常用來顯示數學公式或程式碼。
  

參考文章：
http://www.javatwofriday.com.tw/member/javamag_article/J040901502.pdf
http://www.javatwofriday.com.tw/member/javamag_article/J041001601.pdf
How to Write Doc Comments for the Javadoc Tool
Javadoc Reference Guide