Java檔案注釋（拓展）
學而不思則罔，思而不學則殆， ——《論語·為政》
Java的三種注釋：
* 單行注釋
* 多行注釋
* 檔案注釋
Java檔案注釋：
使用 /* */ 將檔案注釋內容括起來，
檔案注釋概覽
檔案注釋只負責描述類(class)、介面(interface)、方法(method)、構造器(constructor)、成員欄位(field)，
相應地，檔案注釋必須寫在類、介面、方法、構造器、成員欄位前面，而寫在其他位置，比如函式內部，是無效的檔案注釋，
例如：
類注釋，
類注釋用于說明整個類的功能、特性等，它應該放在所有的“import”陳述句之后，在class定義之前，這個規則也適用于介面注釋，
方法注釋，
方法注釋用來說明方法的定義，比如，方法的引數、回傳值及說明方法的作用等，方法注釋應該放在它所描述的方法定義前面，
檔案注釋內容
由描述部分和標記部分組成，
描述部分就是功能介紹、方法解釋等的內容；
標記部分前有標記標簽，例如@author、@version......
描述部分
描述部分的第一行應該是一句對類、介面、方法等的簡單描述，這句話最后會被 javadoc 工具提取并放在索引目錄中，
跟在第一個英文句號之后的tab、空行或行終結符規定了第一句的結尾，
除了普通的文本之外，描述部分可以使用：
-
HTML語法標簽，例如 xxx
-
javadoc規定的特殊標簽，例如 {@link xxx} ，
標簽的語法規則是：{@標簽名 標簽內容}
需要注意的地方：
-
標簽在有javadoc工具生成檔案時會轉化成特殊的內容，比如 {@link URL} 標簽會被轉化成指向URL類的超鏈接
-
如果注釋包含多段內容，段與段之間需要用 <p> 分隔，空行是沒用的
-
為了避免一行過長影響閱讀效果，務必將每行的長度限制在80個字符以內
-
善用javadoc工具的復制機制避免不必要的注釋：
如果一個方法覆寫了父類的方法或實作了介面種的方法，那么javadoc工具會在該注釋里添加指向原始方法的鏈接，此外如果新方法沒有注釋，那么javadoc會把原始方法的注釋復制一份作為其注釋，但是如果新方法有注釋了，就不會復制了，
標記部分
標記部分跟在描述部分之后，且前面必須有一個空行間隔
所有標簽：
| 標簽 | 描述 |
|---|---|
| @author | 標識一個類的作者 |
| @deprecated | 指名一個過期的類或成員 |
| {@docRoot} | 指明當前檔案根目錄的路徑 |
| @exception | 標志一個類拋出的例外 |
| {@inheritDoc} | 從直接父類繼承的注釋 |
| {@link} | 插入一個到另一個主題的鏈接 |
| {@linkplain} | 插入一個到另一個主題的鏈接，但是該鏈接顯示純文本字體 |
| @param | 說明一個方法的引數 |
| @return | 說明回傳值型別 |
| @see | 指定一個到另一個主題的鏈接 |
| @serial | 說明一個序列化屬性 |
| @serialData | 說明通過writeObject( ) 和 writeExternal( )方法寫的資料 |
| @serialField | 說明一個ObjectStreamField組件 |
| @since | 標記當引入一個特定的變化時 |
| @throws | 和 @exception標簽一樣. |
| {@value} | 顯示常量的值，該常量必須是static屬性， |
| @version | 指定類的版本（不是Java版本） |
常見標簽:
- @author 作者，沒有特殊格式要求，名字或組織名稱都可以
- @version 軟體版本號（注意不是java版本號），沒有特殊格式要求
- @param 方法引數，格式為： @param 引數名稱 引數描述
-
可以在引數描述中說明引數的型別
-
可以在引數名稱和引數描述之間添加額外的空格來對齊
-
破折號或其他標點符號不能出現在引數描述之外的地方
-
@return 方法回傳值，格式為： @return 回傳值描述 ，如果方法沒有回傳值就不要寫@return
-
@deprecated 應該告訴用戶這個API被哪個新方法替代了，隨后用 @see 標記或 {@link} 標記指向新API，比如：
/**
* @deprecated As of JDK 1.1, replaced by
* {@link #setBounds(int,int,int,int)}
*/
- @throws （或 @exception ）包含方法顯式拋出的檢查例外(Checked Exception)，至于非顯示拋出的其他例外(Unchecked Exception)，除非特別有必要，否則就別寫了，一個原則就是，只記錄可控的問題，對于不可控的或不可預測的問題，不要往上面寫，
檢查例外：在try語法塊中觸發，在catch塊中捕獲的例外，這些例外會由編譯器在編譯階段檢查并強制程式員處理
非檢查例外：包括運行時例外(RuntimeException)和錯誤(Error)，
- 自定義標記
注釋風格：
- 按照如下順序提供標記
@author（只出現在類和介面的檔案中）
@version（只出現在類和介面的檔案中）
@param（只出現在方法或構造器的檔案中）
@return（只出現在方法中）
@exception（從java1.2之后也可以使用@thrown替代）
@see
@since
@serial（也可以使用@serialField或@serialData替代）
@deprecated
此外，如果有多個相同標記，也要注意順序：
多個@author標記，應該按照時間順序排列，即原作者應該排在第一個位置
多個@param標記，應該按照引數定義的順序排列
多個@exception（或是@thrown）應該按照例外的字母順序排列
多個@see標記，應該按照注釋的邏輯順序排列，即從最近的到最遠的，從最具體的到最一般的
- 必須包含的標記
如果方法有引數，@param標記必須包含，而且每個對應一個引數
如果方法有回傳值，@return標記必須包含
其他注釋
- 包級別的檔案注釋
從java1.2起允許包級別的檔案注釋，用以描述包資訊，每個包都可以有自己的包檔案注釋，這些注釋被寫在叫package.html的單獨檔案中，并且放至于與原始碼(*.java)相同的路徑下，注意，一定不能單獨放置在其他路徑，
javadoc工具按照以下流程處理package.html:
把主要內容復制到最終生成的package-summary.html檔案中
處理@see, @since, 或{@link}標記
把第一句話復制到javadoc的索引中
在包注釋主要介紹一下這個包大致是做什么用的、背景資訊、在使用方面需要注意的地方等等資訊
- 匿名、內部類的檔案注釋
javadoc不會提取內部類的檔案注釋，所以如果想要在最終生成的檔案中包含內部類的資訊，方法就是——寫在外部類的檔案注釋里，
檔案注釋生成檔案時中文亂碼問題
撰寫檔案注釋：
命令列視窗輸入javadoc命令生成檔案，發現出現以下報錯：
原因：
是因為命令列視窗當前的編碼為GBK，而檔案注釋里存在中文，GBK編碼不支持中文，從而導致亂碼，（右鍵視窗白色部分點擊屬性查看命令列視窗編碼）
解決方法：只需要在 javadoc 命令后加入引數 -encoding utf-8 -charset utf-8
解釋一下上述引數的意思：
-d：生成一個檔案夾接受生成的檔案檔案，后面的 HelloDoc 為檔案夾名，
-author、-version：為顯示檔案的作者和版本，對應檔案注釋里的@author、@version，
-encoding utf-8 -charset utf-8：則是將該檔案注釋的編碼解碼形式修改為utf-8，從而解決中文亂碼問題，
通過上述操作，就能看到在Java檔案目錄下生成一個HelloDoc檔案夾，
點擊index.html檔案就可以看到我們的注釋檔案，
后記
本文章檔案注釋內容部分取自文章（https://www.cnblogs.com/boring09/p/4274893.html ），有刪減，
能力有限，難免有遺漏或錯誤，如有發現望指正，
轉載請註明出處，本文鏈接：https://www.uj5u.com/houduan/429241.html
標籤：Java
上一篇：Spring AOP
下一篇：3-面向物件(2)