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/429256.html

標籤：其他

上一篇：Spring AOP

下一篇：SpringBoot自動裝配