使用 Gradle 生成 Javadoc

一、概述

眾所周知，創建清晰全面的文檔對於代碼維護至關重要。在 Java 中執行此操作的一種方法是使用 Javadoc，它是一種文檔生成器，可根據 Java 源代碼註釋創建 HTML 文件。

在本教程中，我們將學習如何使用流行的構建自動化工具 Gradle 生成 Javadoc。

2. 建立一個 Gradle 項目

簡而言之，設置 Gradle 項目非常簡單。首先，我們需要在我們的機器上安裝Gradle 構建工具。接下來，讓我們創建一個空文件夾並通過終端切換到該文件夾。然後，讓我們通過終端初始化一個新的 Gradle 項目：

$ gradle init

該命令會詢問我們一些問題來設置項目。我們將選擇一個應用程序模板作為要生成的項目類型。接下來，我們將選擇 Java 作為實現語言，並選擇 Groovy 作為構建腳本。最後，我們將使用默認的測試框架，即 JUnit 4，並為我們的項目命名。

或者，我們也可以使用 IntelliJ IDEA 生成 Gradle 工程。為此，我們創建一個新項目並選擇 Gradle 作為構建系統。它會自動生成包含所有必需文件夾的項目。

3.項目設置

初始化 Gradle 項目後，讓我們用我們最喜歡的 IDE 打開項目。接下來，我們將創建一個名為“ addition ”的新包並添加一個名為Sum的類：

package com.baeldung.addition

 /**
 * This is a sample class that demonstrates Javadoc comments.
 */
 public class Sum {
 /**
 * This method returns the sum of two integers.
 *
 * @param a the first integer
 * @param b the second integer
 * @return the sum of a and b
 */
 public int add(int a, int b) {
 return a + b;
 }
 }

此類演示了簡單的加法功能。我們創建一個add()方法，它接受兩個參數並返回參數的總和。

此外，我們添加了介紹性文檔註釋，並在註釋中描述了add()方法。我們指定它接受的參數和它返回的值。

接下來，讓我們創建另一個名為“ subtraction ”的包並添加一個名為Difference的類：

package com.baeldung.subtraction

 /**
 * This is a sample class that demonstrates Javadoc comments.
 */
 public class Difference {
 /**
 * This method returns the difference between the two integers.
 *
 * @param a the first integer
 * @param b the second integer
 * @return the difference between a and b
 */
 public int subtract(int a, int b) {
 return a - b;
 }
 }

此類演示了一種查找兩個Integer之間差異的簡單方法。

在下一節中，我們將學習如何通過指定要包含和排除的包來生成 Javadoc。

5. 使用 Gradle 生成 Javadoc

現在我們有了一個帶有文檔註釋的示例項目，我們想通過 Gradle 生成 Javadoc。為此，我們需要在gradle.build文件中添加一些配置。該文件包含項目的配置，例如插件、依賴項、項目組、版本等。

首先，讓我們將 Java 插件應用到項目中：

plugins {
 id 'java'
 }

這告訴 Gradle 使用 Java 插件。 Java 插件使開發 Java 應用程序變得更加容易，並提供編譯、代碼測試、Javadoc 任務等功能。

此外，我們將為 Javadoc 任務將代碼添加到gradle.build文件中：

javadoc {
 destinationDir = file("${buildDir}/docs/javadoc")
 }

這將配置 Javadoc 任務並指定構建目錄以存儲生成的文檔。

我們還可以將 Javadoc 任務配置為在運行任務時包含和排除包：

javadoc {
 destinationDir = file("${buildDir}/docs/javadoc")
 include 'com/baeldung/addition/**'
 exclude 'com/baeldung/subtraction/**'
 }

這裡，我們包含addition包，排除subtraction包。 include和exclude屬性允許我們在 Javadoc 任務中選擇我們想要的包。

最後，為了生成文檔，讓我們打開終端並切換到根文件夾。然後，讓我們運行 Gradle 構建命令：

./gradlew javadoc

此命令執行 Javadoc 任務並生成 HTML 格式的文檔。 HTML 文件存儲在指定的文件夾中。

以下是 HTML 文件文檔的示例：

六，結論

在本文中，我們學習瞭如何使用 Gradle 構建系統生成 Javadoc。此外，我們還了解瞭如何為兩個 Java 類編寫文檔註釋。此外，我們還學習瞭如何配置 Javadoc 以包含和排除包。

與往常一樣，示例的完整源代碼可在 GitHub 上獲得。