使用 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 上獲得。