傳統詳細設計文件與原始碼分離,一致性難維護。Javadoc 以「寄生於原始碼的註解」為核心,實現自文件化:程式碼異動時順手更新註解,文件永遠同步。本文深入解析 JDK 標準 Javadoc 文件結構與 JBuilder 支援功能。
打開 <JBuilder>/doc/jdk_docs.jar 解壓後的 index.html,三框架結構:
| 頁面 | 用途 |
|---|---|
| Overview | 所有套件說明列表 |
| Package | 套件內類別/介面列表 |
| Class | 當前類別(無連結) |
| Use | 類別關聯:繼承、依賴、關聯 |
| Tree | 繼承/實作階層樹 |
| Deprecated | 所有過時 API |
| Index | 字母序索引,快速定位 |
| Help | Javadoc 使用說明 |
@todo 並瀏覽管理「程式碼與註解同檔」是關鍵。編碼時調整註解舉手之勞,一致性成本極低。這正是享元模式思想在文件層面的體現:單一事實來源。