4.9 java文檔註釋之@param等註釋含義

---

前言

• JDK 包含一個很有用的工具，叫做javadoc, 它可以由源文件生成一個 HTML 文檔。
• 聯機 API 文檔就是通過對標準 Java 類庫的源代碼運行 javadoc 生 成的。 - 如果在源代碼中添加以專用的定界符 /**開始的註釋， 那麼可以很容易地生成一個看上 去具有專業水準的文檔。這是一種很好的方式，因爲這種方式可以將代碼與註釋保存在一個 地方。
• 如果將文檔存人一個獨立的文件中， 就有可能會隨着時間的推移， 出現代碼和註釋不 一致的問題。然而，由於文檔註釋與源代碼在同一個文件中，在修改源代碼的同時， 重新運 行javadoc 就可以輕而易舉地保持兩者的一致性。

一、類註釋

• 類註釋必須放在 import 語句之後，類定義之前。
• 這裏參考網上的設置方法，用的是IDEA，改變了註釋的顯示方式
• IDEA註解參考鏈接
  

二、方法註釋

• 每一個方法註釋必須放在所描述的方法之前。除了通用標記之外， 還可以使用下面的標記：

• @param 變量描述
  這個標記將對當前方法的“ param” （參數）部分添加一個條目。這個描述可以佔據多 行， 並可以使用 HTML 標記。一個方法的所有@param 標記必須放在一起。

• @return 描述 這個標記將對當前方法添加“ return” （返回）部分。
  這個描述可以跨越多行， 並可以 使用 HTML 標記。

• @throws 類描述 這個標記將添加一個註釋， 用於表示這個方法有可能拋出異常

• …
  

三、域註釋

• 只需要對公有域（通常指的是靜態常量）建立文檔。

/** 
* The "Hearts" card suit V 
*/
public static final int HEARTS = 1 ;

四、通用註釋

下面的標記可以用在類文檔的註釋中。

• @author 姓名
  這個標記將產生一個 ** author" (作者）條目。可以使用多個@author 標記，每個@ author 標記對應一個作者
• @version 版本
  這個標記將產生一個“ version”（版本）條目。這裏的文本可以是對當前版本的任何描 述。

下面的標記可以用於所有的文檔註釋中。

• @since 文本
  這個標記將產生一個“ since” （始於）條目。這裏的 text 可以是對引人特性的版本描 述。例如，@since version 1.7.10
• @deprecated 這個標記將對類、方法或變量添加一個不再使用的註釋。
  文本中給出了取代的建議。
  例如， @deprecated Use setVIsible(true) instead
  通過@see 和@link標記，可以使用超級鏈接， 鏈接到 javadoc 文檔的相關部分或外 部文檔。
• @see 引用
  這個標記將在“ see also” 部分增加一個超級鏈接。它可以用於類中，也可以用於方 法中。這裏的引用可以選擇下列情形之一：

/**
* @see JavaSE.Chapter4.Section47.cs471.testMothod#test()
* @see <a href="www.bithachi.cn">BitHachi</a>
*/