Java API 文件中的程式碼片段

1. 概述

全面的文件可協助開發人員輕鬆使用庫。 Javadoc 是一個很棒的工具，可以幫助產生 Java 程式碼文件。 Java 18 引入了@snippet標籤，可以輕鬆地將程式碼片段整合到文件中。

在本教學中，我們將探索如何使用@snippet標籤將程式碼片段新增至文件。

2. @snippet標籤之前

在 Java 18 之前，我們可以使用@code標籤在文件中新增程式碼片段。然而，這也有一些限制。

@code標籤將代碼視為普通文字。它不驗證程式碼片段和突出顯示語法。

3.使用@snippet標籤

Java 18 引入了@snippet標籤來解決@code標籤的限制。它具有突出顯示代碼語法的功能。

此外，它還可以輕鬆地將程式碼嵌入到文件中。它還具有將外部原始碼添加到文件中的功能。

此外，也可以使用編譯器樹 API 來驗證程式碼片段。

@snippet標籤可以透過兩種不同的方式使用 -內聯程式碼片段和外部程式碼片段。

3.1.內聯程式碼片段

內聯程式碼片段有助於透過將程式碼明確放入@snippet標記內來將程式碼片段新增至 Javadoc 註解。

@snippet標籤具有左大括號和右大括號。程式碼片段寫在冒號後面。此外，程式碼片段必須位於大括號內：

{@snippet : "placeholder for code snippets" }

以下是使用內聯程式碼片段的文件範例：

/**
 * The code below shows the content of {@code helloBaeldung()} method
 * {@snippet :
 * public void helloBaeldung() {
 * System.out.println("Hello From Team Baeldung");
 * }
 * }
 */
 public class GreetingsInlineSnippet {
 public void helloBaeldung() {
 System.out.println("Hello From Team Baeldung");
 }
 }

在上面的程式碼中，我們加入了文件中的helloBaeldung()方法。首先，我們定義@snippet標籤。然後，我們將程式碼片段寫入標籤內。

這是生成的 Javadoc：

上圖顯示了文件中嵌入的內嵌程式碼片段。

3.2.外部程式碼片段

此外，我們可以將外部文件或類別中的程式碼片段新增到文件中。首先，我們必須使用@start和@end標籤指定要新增的區域。

讓我們寫一些簡單的文件來展示在 Java 中實作二分搜尋的方法。

首先，讓我們建立一個名為BinarySearch的類，其中包含實現二分搜尋的方法並指定要新增到文件中的部分：

public class BinarySearch {
 public int search(int[] list, int item) {
 int index = Integer.MAX_VALUE;
 int low = 0;
 int high = list.length - 1;

 // @start region="binary"
 while (low <= high) {
 int mid = high - low;
 int guess = list[mid];
 if (guess == item) {
 index = mid; break;
 } else if (guess > item) {
 low = mid - 1;
 } else {
 low = mid + 1;
 }
 low++;
 }
 // @end region="binary"
 return index;
 }
 }

在上面的程式碼中，我們想要將名為「 binary 」的區域加入到GreetingsExternalSnippet類別的文件中。我們使用@start標籤來標記開始區域，使用@end標籤來標記結束區域。

此外， 「 binary 」是標記區域的唯一名稱，它可以用來呼叫任何Javadoc中的部分。

讓我們將程式碼加入到GreetingsExternalSnippet類別中的 Javadoc 註解中：

/**
 *
 * External code snippet showing the loop process in binary search method.
 * {@snippet class="BinarySearch" region="binary"}
 */

 public class GreetingsExternalSnippet {
 public void helloBinarySearch() {
 System.out.println("Hi, it's great knowing that binary search uses a loop under the hood");
 }
 }

在這裡，我們透過提供正確的類別名稱和區域名稱，使用@snippet標籤來呼叫外部檔案。另外，我們需要將外部類別或檔案放在名為snippet-files目錄中，以便 Javadoc 指令可以辨識外部檔案或類別的路徑。

要產生 Javadoc，我們需要使用–snippet-path選項指定資料夾snippet-files ，以避免生成文件時出現錯誤：

$ javadoc -d doc com.baeldung.snippettag --snippet-path snippet-files

上面的命令產生文檔。

這是生成的 Javadoc：

名為binary的部分已成功匯入到文件中。

值得注意的是，我們也可以使用檔案屬性從屬性檔案、設定檔等檔案匯入片段。

下面的範例顯示了具有已定義區域的屬性檔案：

# @start region="zone"
 local.timezone = GMT+1
 local.zip = 94123
 # @end region="zone"

接下來，讓我們使用file屬性將定義的「 zone 」嵌入到 Javadoc 註解中：

/**
 * Time Zone
 * {@snippet file="application.properties" region="zone"}
 *
 */
 public class GreetingsExternalSnippet {
 public void helloBinarySearch() {
 System.out.println("Hi, it's great knowing that binary search uses a loop under the hood");
 }
 }

在這裡，我們使用file屬性來定義檔案的名稱。

這是產生的文檔：

上圖顯示了屬性檔中的片段。

3.3. @highlight標籤

此外，我們可以使用@highlight標籤來突出顯示程式碼片段的一部分以引起注意。

讓我們修改helloBaeldung()方法以反白將問候語印到控制台的部分：

/**
 * {@snippet :
 * public void helloBaeldung() {
 * System.out.println("Hello From Team Baeldung"); // @highlight
 * }
 * }
 */

在這裡， @highlight標籤突出顯示了我們聲明它的行：

此外，我們可以更具體地突出顯示字串：

/**
 * {@snippet :
 * public void helloBaeldung() {
 * System.out.println("Hello From Team Baeldung"); // @highlight substring="println"
 * }
 * }
 */

在這裡，我們使用substring屬性來突出顯示“ println ”：

此外，我們可以透過使用region屬性和@end標籤來擴展@highlight標籤的範圍：

/**
 * highlighting texts on multiple lines
 * {@snippet :
 * public void helloBaeldung() {
 * System.out.println("Hello From Team Baeldung"); // @highlight region substring="println"
 * String country = "USA";
 * System.out.println("Hello From Team " + country); // @end
 *
 * }
 * }
 */

上面的程式碼使用region屬性來定義要反白的子字串範圍的開頭。最後，我們使用@end標籤來標記範圍的結束。

產生的文件突出顯示指定的子字串：

這裡，子字串“ println ”在指定範圍內被反白。

3.4. @replace標籤

@replace標籤有助於修改程式碼片段中的文字。

讓我們來看一個使用@replace標籤的範例：

/**
 * {@snippet :
 * public void helloBaeldung() {
 * System.out.println("Hello From Team Baeldung"); // @replace regex='".*"' replacement="..."
 * }
 * }
 */

在這裡，我們用三個點替換顯示的文字：

當我們想要修改顯示的文字時，這非常有用。

3.5. @link標籤

我們可以使用@link標籤連結到現有文件。

首先，我們在程式碼片段中定義@link標籤。然後，我們指定文字和目標連結：

/**
 * Linking Text
 * {@snippet :
 * public void helloBaeldung() {
 * System.out.println("Hello From Team Baeldung"); // @link substring="System.out" target="System#out"
 * }
 * }
 */

上面的程式碼將System.out連結到有關如何使用它的官方文件。

這是生成的 Javadoc：

它表明System.out上有一個連結。

4。結論

在本文中，我們學習如何使用@snippet標籤將程式碼片段加入 Javadoc 註解。此外，我們還了解如何將內聯和外部程式碼片段與其他標籤和屬性一起使用。

與@code標籤相比， @snippet標籤提供了簡單的程式碼整合。語法突出顯示和程式碼驗證使@snippet成為出色的 Javadoc 工具。

與往常一樣，範例的完整原始程式碼可在 GitHub 上取得。