如何在 Javadocs 中分隔段落
1. 簡介
在大型程式碼庫中，編寫良好的 Javadoc 與程式碼本身同等重要。增強 Javadoc 可讀性最簡單的技巧之一是將長描述拆分為可讀的段落。然而，由於 Javadoc 的標記規範有些過時，這項技巧經常被錯誤地應用。
在本教程中，我們將探討在 Javadocs 中建立段落分隔符的正確方法、段落分隔符號的重要性以及無法正確插入段落分隔符號的一些常見陷阱。
2. 段落分隔為何重要
讀者通常會快速瀏覽文檔，密集的文字會降低閱讀速度，並掩蓋關鍵思想。結構清晰、段落清晰的文檔具有以下優點：
- 突顯不同的概念
- 避免可怕的“文字牆”
- 改進生成的 HTML（反映段落結構）
- 確保 Checkstyle 等自動化文件註解分析器正常運作
3. Javadoc段落的基本語法
Javadoc 工具將任何連續的文字視為一個段落。具體來說，開始新段落的規範方法是將 HTML <p>標籤放在新行的開頭：
/**
* Returns a greeting for the provided name.
* <p>
* This method does not perform any validation,
* so callers must ensure that {@code name} is non-null
* and non-blank.
*/
public String greet(String name) { … }
<p>標籤之前的所有內容都是第一段。標籤之後直到描述結束的所有內容都是第二段。
3.1. 為什麼只有一個打開的<p>標籤？
與現代 HTML（其中段落由<p>和</p>分隔）不同， Javadoc 僅需要開始標記。此外，結束標記是隱含的，並由產生最終 HTML 的 doclet 插入。如果我們加入文字</p>,它將逐字輸出，並在輸出中顯示為雜散文本。
3.2. Javadoc 的 HTML 繼承
Javadoc 對<p>標籤的處理可以追溯到HTML 3.2 規範（1997 年），該規範允許使用獨立的起始段落標籤，並且標籤名稱不區分大小寫。因此，Javadoc 解析器仍然接受大寫的<P>標籤。此外，雖然小寫<p>如今已成為標準，但我們在查看較舊的 Java 程式碼時仍可能經常遇到<P> 。
4. 常見陷阱
嘗試分段時，我們需要注意一些常見的錯誤，以便避免它們。本節中的範例看起來似乎可以建立新的段落，但實際上卻無法建立。
4.1. 僅空白行
註解來源中的空白行不會在產生的 HTML 中產生新段落：
/**
* Computes the checksum.
*
* This sentence _looks_ like a second paragraph,
* but because there is no <p> tag, the HTML generation
* merges everything into a single block.
*/
4.2. 內嵌標籤
<p>之前的額外前導星號或空格是可以的，但標籤必須始終開始新的邏輯行：
/**
* Computes the checksum. <p>This inline tag does **not**
* start a new paragraph because it is not placed at the
* beginning of a new logical line inside the comment.
*/
4.3. Markdown 文法
在 Markdown 語法中，段落是指任何由一個或多個空白行分隔的文字區塊。因此，GitHub 上的 README.md 檔案會將區塊間帶有空行的文字渲染為單獨的段落。然而，Javadoc 工具會折疊空格，並且不會將空白行視為**段落分隔符號**。
讓我們看一個註解區塊的範例，該註解區塊在傳統的 Markdown 渲染器中會以段落分隔符號顯示，但在 Javadoc 渲染器中不會顯示段落分隔符號：
/**
* Computes the checksum.
*
*
* Two trailing spaces create a line break in Markdown,
* yet the Javadoc tool collapses whitespace, leaving
* the description as one paragraph.
*/5. 結論
清晰的段落分隔對於 Java 文件來說，是一項省力又有效率的補充。通常，每當我們在普通文件中按下Enter開始一個新的想法時，都應該在 Javadoc 中插入一個<p>標籤。結合自動檢查和 IDE 支持，這個簡單的習慣有助於保持 API 文件的可讀性和專業性。