[TOC]
<!-- Appendix: Javadoc -->
# 附錄:文檔注釋
編寫代碼文檔的最大問題可能是維護該文檔。如果文檔和代碼是分開的,每次更改代碼時都要很繁瑣地再去更改文檔。解決方案似乎很簡單:將代碼鏈接到文檔。最簡單的方法是將所有內容放在同一個文件中。然而,要完成這個任務,需要一個特殊的注釋語法來標記文檔,以及一個工具將這些注釋提取為有用的形式,這就是Java所做的。
提取注釋的工具稱為Javadoc,它是 JDK 安裝的一部分。它使用Java編譯器中的一些技術來尋找特殊的注釋標記。它不僅提取由這些標記所標記的信息,還提取與注釋相鄰的類名或方法名。通過這種方式,您就可以用最少的工作量來生成合適的程序文檔。
Javadoc的輸出是一個html文件,可以用web瀏覽器查看它。有了Javadoc,就有一個簡單的標準來創建文檔,因此你可以期望所有Java庫都有文檔。
此外,你可以編寫自己的Javadoc處理程序doclet,對javadoc處理的信息做特殊的處理(例如以不同的格式生成輸出)。
以下是對Javadoc基礎知識的介紹和概述。在 JDK 文檔中可以找到完整的描述。
## 句法規則
所有Javadoc指令都發生在以 `/**` 開頭(但仍然以 `*/`)結尾)的注釋中。使用Javadoc有兩種主要方法:嵌入HTML或使用“doc標簽”。獨立的doc標簽是以 **@** 開頭并且放在注釋行的開頭的指令(注釋行開頭的`*`將被忽略)。內聯的doc標簽可以出現在Javadoc注釋的任何位置,它也以 `@` 開頭,但被花括號包圍。
有三種類型的注釋文檔,它們對應于注釋前面的元素:類、字段或方法。也就是說,類注釋出現在類定義之前,字段注釋出現在字段定義之前,方法注釋出現在方法定義之前。舉個簡單的例子:
```java
// javadoc/Documentation1.java
/** 一個類注釋 */
public class Documentation1 {
/** 一個屬性注釋 */
public int i;
/** 一個方法注釋 */
public void f() {}
}
```
Javadoc僅處理 **公共成員** 和 **繼承訪問權限成員** 的注釋文檔。 默認情況下,將忽略對 **私有成員** 和**包訪問權限成員**的注釋(請參閱["隱藏實現"](/docs/book/07-Implementation-Hiding.md)一章),并且你將看不到任何輸出。 這是有道理的,因為從客戶端程序員的視角看,在文件外部只有 **公共成員** 和 **繼承訪問權限成員** 是可用的。 你可以使用 **-private** 標志來包含 **私有成員**。
要通過Javadoc處理前面的代碼,命令是:
```cmd
javadoc Documentation1.java
```
這將產生一組HTML文件。如果你在瀏覽器中打開index.html,將看到輸出的結果與其他Java文檔具有相同的標準格式,因此使用者對這種格式很熟悉,并可以輕松地瀏覽你的類。
## 內嵌 HTML
Javadoc不作修改地將HTML代碼傳遞到生成的HTML文檔。這使你可以充分利用HTML。但是這樣做的主要目的是讓你格式化代碼,例如:
```java
// javadoc/Documentation2.java
/** <pre>
* System.out.println(new Date());
* </pre>
*/
public class Documentation2 {}
```
你也可以像在其他任何Web文檔中一樣使用HTML來格式化說明中的文字:
```java
// javadoc/Documentation3.java
/** You can <em>even</em> insert a list:
* <ol>
* <li> Item one
* <li> Item two
* <li> Item three
* </ol>
*/
public class Documentation3 {}
```
請注意,在文檔注釋中,Javadoc會刪除行首的星號以及前導空格。 Javadoc重新格式化了所有內容,使其符合文檔的標準外觀。不要將`<h1>` 和`<hr>` 之類的標題用作嵌入式HTML,因為Javadoc會插入自己的標題,你插入的標題將對其產生干擾。
所有類型的注釋文檔(類,字段和方法)都可以支持嵌入式HTML。
## 示例標簽
以下是一些可用于代碼文檔的Javadoc標記。在嘗試使用Javadoc進行任何認真的操作之前,請查閱JDK文檔中的Javadoc參考,以了解使用Javadoc的所有不同方法。
### @see
這個標簽可以將其它的類鏈接到本文檔中。Javadoc 用 `@see` 標簽產生鏈接到其它類的的HTML。格式為:
```java
@see classname
@see fully-qualified-classname
@see fully-qualified-classname#method-name
```
每個都向生成的文檔中添加超鏈接的“另請參閱”條目。 Javadoc 不會檢查超鏈接的有效性。
### {@link package.class#member label}
和 @see 非常相似,不同之處在于它可以內聯使用,并使用標簽作為超鏈接文本,而不是“另請參閱”。
### {@docRoot}
生成文檔根目錄的相對路徑。對于顯式超鏈接到文檔樹中的頁面很有用。
### {@inheritDoc}
將文檔從此類的最近基類繼承到當前文檔注釋中。
### @version
其形式為:
```java
@version version-information
```
其中 version-information 是你認為適合包含的任何重要信息。當在Javadoc命令行上放置 -version 標志時,特別在生成的HTML文檔中用于生成version信息。
### @author
其形式為:
```
@author author-information
```
author-information 大概率是你的名字,但是一樣可以包含你的 email 地址或者其他合適的信息。當在 Javadoc 命令行上放置 -author 標志的時候,在生成的HTML文檔中特別注明了作者信息。
你可以對作者列表使用多個作者標簽,但是必須連續放置它們。所有作者信息都集中在生成的HTML中的單個段落中。
### @since
此標記指示此代碼的版本開始使用特定功能。例如,它出現在HTML Java文檔中,以指示功能首次出現的JDK版本。
### @param
這將生成有關方法參數的文檔:
```java
@param parameter-name description
```
其中 `parameter-name` 是方法參數列表中的標識符, `description` 是可以在后續行中繼續的文本。當遇到新的文檔標簽時,這個說明被視為結束。`@param`標簽可以使用任意次,大概每個參數使用一次。
### @return
這記錄了返回值:
```java
@return description
```
其中description給出了返回值的含義。它可延續到后面的行內。
### @throws
一個方法可以產生許多不同類型的異常,所有這些異常都需要描述。異常標記的形式為:
```java
@throws fully-qualified-class-name description
```
*fully-qualified-class-name* 給出異常類的確切名稱,并且 description (可在后面的行內繼續展開)告訴你為什么這個特定類型的異常會在方法調用后出現。
### @deprecated
表示已被改進的功能取代的功能。deprecated 標記建議你不要再使用此功能,因為將來它有可能被刪除。使用標記為 `@deprecated` 的方法會使編譯器發出警告。在Java 5中,`@deprecated` Javadoc 標記被 `@Deprecated` *注解* 取代(在[注解]()一章中進行了描述)。
## 文檔示例
**objects/HelloDate.java** 是帶有文檔注釋的例子。
```java
// javadoc/HelloDateDoc.java
import java.util.*;
/** The first On Java 8 example program.
* Displays a String and today's date.
* @author Bruce Eckel
* @author www.MindviewInc.com
* @version 5.0
*/
public class HelloDateDoc {
/** Entry point to class & application.
* @param args array of String arguments
* @throws exceptions No exceptions thrown
*/
public static void main(String[] args) {
System.out.println("Hello, it's: ");
System.out.println(new Date());
}
}
/* Output:
Hello, it's:
Tue May 09 06:07:27 MDT 2017
*/
```
你可以在Java標準庫的源代碼中找到許多Javadoc注釋文檔的示例。
<!-- 分頁 -->
<div style="page-break-after: always;"></div>
- 譯者的話
- 前言
- 簡介
- 第一章 對象的概念
- 抽象
- 接口
- 服務提供
- 封裝
- 復用
- 繼承
- "是一個"與"像是一個"的關系
- 多態
- 單繼承結構
- 集合
- 對象創建與生命周期
- 異常處理
- 本章小結
- 第二章 安裝Java和本書用例
- 編輯器
- Shell
- Java安裝
- 校驗安裝
- 安裝和運行代碼示例
- 第三章 萬物皆對象
- 對象操縱
- 對象創建
- 數據存儲
- 基本類型的存儲
- 高精度數值
- 數組的存儲
- 代碼注釋
- 對象清理
- 作用域
- 對象作用域
- 類的創建
- 類型
- 字段
- 基本類型默認值
- 方法使用
- 返回類型
- 參數列表
- 程序編寫
- 命名可見性
- 使用其他組件
- static關鍵字
- 小試牛刀
- 編譯和運行
- 編碼風格
- 本章小結
- 第四章 運算符
- 開始使用
- 優先級
- 賦值
- 方法調用中的別名現象
- 算術運算符
- 一元加減運算符
- 遞增和遞減
- 關系運算符
- 測試對象等價
- 邏輯運算符
- 短路
- 字面值常量
- 下劃線
- 指數計數法
- 位運算符
- 移位運算符
- 三元運算符
- 字符串運算符
- 常見陷阱
- 類型轉換
- 截斷和舍入
- 類型提升
- Java沒有sizeof
- 運算符總結
- 本章小結
- 第五章 控制流
- true和false
- if-else
- 迭代語句
- while
- do-while
- for
- 逗號操作符
- for-in 語法
- return
- break 和 continue
- 臭名昭著的 goto
- switch
- switch 字符串
- 本章小結
- 第六章 初始化和清理
- 利用構造器保證初始化
- 方法重載
- 區分重載方法
- 重載與基本類型
- 返回值的重載
- 無參構造器
- this關鍵字
- 在構造器中調用構造器
- static 的含義
- 垃圾回收器
- finalize()的用途
- 你必須實施清理
- 終結條件
- 垃圾回收器如何工作
- 成員初始化
- 指定初始化
- 構造器初始化
- 初始化的順序
- 靜態數據的初始化
- 顯式的靜態初始化
- 非靜態實例初始化
- 數組初始化
- 動態數組創建
- 可變參數列表
- 枚舉類型
- 本章小結
- 第七章 封裝
- 包的概念
- 代碼組織
- 創建獨一無二的包名
- 沖突
- 定制工具庫
- 使用 import 改變行為
- 使用包的忠告
- 訪問權限修飾符
- 包訪問權限
- public: 接口訪問權限
- 默認包
- private: 你無法訪問
- protected: 繼承訪問權限
- 包訪問權限 Vs Public 構造器
- 接口和實現
- 類訪問權限
- 本章小結
- 第八章 復用
- 組合語法
- 繼承語法
- 初始化基類
- 帶參數的構造函數
- 委托
- 結合組合與繼承
- 保證適當的清理
- 名稱隱藏
- 組合與繼承的選擇
- protected
- 向上轉型
- 再論組合和繼承
- final關鍵字
- final 數據
- 空白 final
- final 參數
- final 方法
- final 和 private
- final 類
- final 忠告
- 類初始化和加載
- 繼承和初始化
- 本章小結
- 第九章 多態
- 向上轉型回顧
- 忘掉對象類型
- 轉機
- 方法調用綁定
- 產生正確的行為
- 可擴展性
- 陷阱:“重寫”私有方法
- 陷阱:屬性與靜態方法
- 構造器和多態
- 構造器調用順序
- 繼承和清理
- 構造器內部多態方法的行為
- 協變返回類型
- 使用繼承設計
- 替代 vs 擴展
- 向下轉型與運行時類型信息
- 本章小結
- 第十章 接口
- 抽象類和方法
- 接口創建
- 默認方法
- 多繼承
- 接口中的靜態方法
- Instrument 作為接口
- 抽象類和接口
- 完全解耦
- 多接口結合
- 使用繼承擴展接口
- 結合接口時的命名沖突
- 接口適配
- 接口字段
- 初始化接口中的字段
- 接口嵌套
- 接口和工廠方法模式
- 本章小結
- 第十一章 內部類
- 創建內部類
- 鏈接外部類
- 使用 .this 和 .new
- 內部類與向上轉型
- 內部類方法和作用域
- 匿名內部類
- 嵌套類
- 接口內部的類
- 從多層嵌套類中訪問外部類的成員
- 為什么需要內部類
- 閉包與回調
- 內部類與控制框架
- 繼承內部類
- 內部類可以被覆蓋么?
- 局部內部類
- 內部類標識符
- 本章小結
- 第十二章 集合
- 泛型和類型安全的集合
- 基本概念
- 添加元素組
- 集合的打印
- 迭代器Iterators
- ListIterator
- 鏈表LinkedList
- 堆棧Stack
- 集合Set
- 映射Map
- 隊列Queue
- 優先級隊列PriorityQueue
- 集合與迭代器
- for-in和迭代器
- 適配器方法慣用法
- 本章小結
- 簡單集合分類
- 第十三章 函數式編程
- 新舊對比
- Lambda表達式
- 遞歸
- 方法引用
- Runnable接口
- 未綁定的方法引用
- 構造函數引用
- 函數式接口
- 多參數函數式接口
- 缺少基本類型的函數
- 高階函數
- 閉包
- 作為閉包的內部類
- 函數組合
- 柯里化和部分求值
- 純函數式編程
- 本章小結
- 第十四章 流式編程
- 流支持
- 流創建
- 隨機數流
- int 類型的范圍
- generate()
- iterate()
- 流的建造者模式
- Arrays
- 正則表達式
- 中間操作
- 跟蹤和調試
- 流元素排序
- 移除元素
- 應用函數到元素
- 在map()中組合流
- Optional類
- 便利函數
- 創建 Optional
- Optional 對象操作
- Optional 流
- 終端操作
- 數組
- 集合
- 組合
- 匹配
- 查找
- 信息
- 數字流信息
- 本章小結
- 第十五章 異常
- 異常概念
- 基本異常
- 異常參數
- 異常捕獲
- try 語句塊
- 異常處理程序
- 終止與恢復
- 自定義異常
- 異常與記錄日志
- 異常聲明
- 捕獲所有異常
- 多重捕獲
- 棧軌跡
- 重新拋出異常
- 精準的重新拋出異常
- 異常鏈
- Java 標準異常
- 特例:RuntimeException
- 使用 finally 進行清理
- finally 用來做什么?
- 在 return 中使用 finally
- 缺憾:異常丟失
- 異常限制
- 構造器
- Try-With-Resources 用法
- 揭示細節
- 異常匹配
- 其他可選方式
- 歷史
- 觀點
- 把異常傳遞給控制臺
- 把“被檢查的異常”轉換為“不檢查的異常”
- 異常指南
- 本章小結
- 后記:Exception Bizarro World
- 第十六章 代碼校驗
- 測試
- 如果沒有測試過,它就是不能工作的
- 單元測試
- JUnit
- 測試覆蓋率的幻覺
- 前置條件
- 斷言(Assertions)
- Java 斷言語法
- Guava斷言
- 使用斷言進行契約式設計
- 檢查指令
- 前置條件
- 后置條件
- 不變性
- 放松 DbC 檢查或非嚴格的 DbC
- DbC + 單元測試
- 使用Guava前置條件
- 測試驅動開發
- 測試驅動 vs. 測試優先
- 日志
- 日志會給出正在運行的程序的各種信息
- 日志等級
- 調試
- 使用 JDB 調試
- 圖形化調試器
- 基準測試
- 微基準測試
- JMH 的引入
- 剖析和優化
- 優化準則
- 風格檢測
- 靜態錯誤分析
- 代碼重審
- 結對編程
- 重構
- 重構基石
- 持續集成
- 本章小結
- 第十七章 文件
- 文件和目錄路徑
- 選取路徑部分片段
- 路徑分析
- Paths的增減修改
- 目錄
- 文件系統
- 路徑監聽
- 文件查找
- 文件讀寫
- 本章小結
- 第十八章 字符串
- 字符串的不可變
- +的重載與StringBuilder
- 意外遞歸
- 字符串操作
- 格式化輸出
- printf()
- System.out.format()
- Formatter類
- 格式化修飾符
- Formatter轉換
- String.format()
- 一個十六進制轉儲(dump)工具
- 正則表達式
- 基礎
- 創建正則表達式
- 量詞
- CharSequence
- Pattern和Matcher
- find()
- 組(Groups)
- start()和end()
- Pattern標記
- split()
- 替換操作
- 正則表達式與 Java I/O
- 掃描輸入
- Scanner分隔符
- 用正則表達式掃描
- StringTokenizer類
- 本章小結
- 第十九章 類型信息
- 為什么需要 RTTI
- Class對象
- 類字面常量
- 泛化的Class引用
- cast()方法
- 類型轉換檢測
- 使用類字面量
- 遞歸計數
- 一個動態instanceof函數
- 注冊工廠
- 類的等價比較
- 反射:運行時類信息
- 類方法提取器
- 動態代理
- Optional類
- 標記接口
- Mock 對象和樁
- 接口和類型
- 本章小結
- 第二十章 泛型
- 簡單泛型
- 泛型接口
- 泛型方法
- 復雜模型構建
- 泛型擦除
- 補償擦除
- 邊界
- 通配符
- 問題
- 自限定的類型
- 動態類型安全
- 泛型異常
- 混型
- 潛在類型機制
- 對缺乏潛在類型機制的補償
- Java8 中的輔助潛在類型
- 總結:類型轉換真的如此之糟嗎?
- 進階閱讀
- 第二十一章 數組
- 數組特性
- 一等對象
- 返回數組
- 多維數組
- 泛型數組
- Arrays的fill方法
- Arrays的setAll方法
- 增量生成
- 隨機生成
- 泛型和基本數組
- 數組元素修改
- 數組并行
- Arrays工具類
- 數組比較
- 數組拷貝
- 流和數組
- 數組排序
- Arrays.sort()的使用
- 并行排序
- binarySearch二分查找
- parallelPrefix并行前綴
- 本章小結
- 第二十二章 枚舉
- 基本 enum 特性
- 將靜態類型導入用于 enum
- 方法添加
- 覆蓋 enum 的方法
- switch 語句中的 enum
- values 方法的神秘之處
- 實現而非繼承
- 隨機選擇
- 使用接口組織枚舉
- 使用 EnumSet 替代 Flags
- 使用 EnumMap
- 常量特定方法
- 使用 enum 的職責鏈
- 使用 enum 的狀態機
- 多路分發
- 使用 enum 分發
- 使用常量相關的方法
- 使用 EnumMap 進行分發
- 使用二維數組
- 本章小結
- 第二十三章 注解
- 基本語法
- 定義注解
- 元注解
- 編寫注解處理器
- 注解元素
- 默認值限制
- 替代方案
- 注解不支持繼承
- 實現處理器
- 使用javac處理注解
- 最簡單的處理器
- 更復雜的處理器
- 基于注解的單元測試
- 在 @Unit 中使用泛型
- 實現 @Unit
- 本章小結
- 第二十四章 并發編程
- 術語問題
- 并發的新定義
- 并發的超能力
- 并發為速度而生
- 四句格言
- 1.不要這樣做
- 2.沒有什么是真的,一切可能都有問題
- 3.它起作用,并不意味著它沒有問題
- 4.你必須仍然理解
- 殘酷的真相
- 本章其余部分
- 并行流
- 創建和運行任務
- 終止耗時任務
- CompletableFuture類
- 基本用法
- 結合 CompletableFuture
- 模擬
- 異常
- 流異常(Stream Exception)
- 檢查性異常
- 死鎖
- 構造方法非線程安全
- 復雜性和代價
- 本章小結
- 缺點
- 共享內存陷阱
- This Albatross is Big
- 其他類庫
- 考慮為并發設計的語言
- 拓展閱讀
- 第二十五章 設計模式
- 概念
- 單例模式
- 模式分類
- 構建應用程序框架
- 面向實現
- 工廠模式
- 動態工廠
- 多態工廠
- 抽象工廠
- 函數對象
- 命令模式
- 策略模式
- 責任鏈模式
- 改變接口
- 適配器模式(Adapter)
- 外觀模式(Fa?ade)
- 包(Package)作為外觀模式的變體
- 解釋器:運行時的彈性
- 回調
- 多次調度
- 模式重構
- 抽象用法
- 多次派遣
- 訪問者模式
- RTTI的優劣
- 本章小結
- 附錄:補充
- 附錄:編程指南
- 附錄:文檔注釋
- 附錄:對象傳遞和返回
- 附錄:流式IO
- 輸入流類型
- 輸出流類型
- 添加屬性和有用的接口
- 通過FilterInputStream 從 InputStream 讀取
- 通過 FilterOutputStream 向 OutputStream 寫入
- Reader和Writer
- 數據的來源和去處
- 更改流的行為
- 未發生改變的類
- RandomAccessFile類
- IO流典型用途
- 緩沖輸入文件
- 從內存輸入
- 格式化內存輸入
- 基本文件的輸出
- 文本文件輸出快捷方式
- 存儲和恢復數據
- 讀寫隨機訪問文件
- 本章小結
- 附錄:標準IO
- 附錄:新IO
- ByteBuffer
- 數據轉換
- 基本類型獲取
- 視圖緩沖區
- 字節存儲次序
- 緩沖區數據操作
- 緩沖區細節
- 內存映射文件
- 性能
- 文件鎖定
- 映射文件的部分鎖定
- 附錄:理解equals和hashCode方法
- 附錄:集合主題
- 附錄:并發底層原理
- 附錄:數據壓縮
- 附錄:對象序列化
- 附錄:靜態語言類型檢查
- 附錄:C++和Java的優良傳統
- 附錄:成為一名程序員