Generating Javadoc With Gradle

1. Overview

As we know, creating clear and comprehensive documentation is essential for code maintenance. One way to do this in Java is by using Javadoc, a documentation generator that creates an HTML file from Java source code comments.

In this tutorial, we’ll learn how to generate Javadoc using Gradle, a popular build automation tool.

2. Setting up a Gradle Project

Simply put, setting up a Gradle project is very easy. First, we need to install Gradle build tool on our machine. Next, let’s create an empty folder and change to the folder via the terminal. Then, let’s initialize a new Gradle project via the terminal:

$ gradle init

The command asks us some questions to set up the project. We’ll choose an application template as the type of project to generate. Next, we’ll choose Java as the implementation language and Groovy as the build script. Finally, we’ll use the default test framework, which is JUnit 4, and give our project a name.

Alternatively, we can also use IntelliJ IDEA to generate a Gradle project. To do this, we create a new project and select Gradle as the build system. It automatically generates the project with all the required folders.

3. Project Setup

After initializing a Gradle project, let’s open the project with our favorite IDE. Next, we’ll create a new package called ‘addition‘ and add a class named 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;
    }
}

This class demonstrates the simple addition functionality. We create an add() method that takes two arguments and returns the sum of the arguments.

Moreover, we add introductory documentation comments and describe the add() method in the comments. We specify the parameter it takes and the value it returns.

Next, let’s create another package called ‘subtraction‘ and add a class named 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;
    }
}

This class demonstrates a simple method that finds differences between two Integers.

In the next section, we’ll learn how to generate Javadoc by specifying the packages to include and exclude.

5. Generate Javadoc With Gradle

Now that we have an example project with documentation comments, we want to generate Javadoc via Gradle. To do this, we need to add some configurations to the gradle.build file. This file contains the configuration for the project, such as plugins, dependencies, project group, version, etc.

First, let’s apply the Java plugin to the project:

plugins {
    id 'java'
}

This tells Gradle to use the Java plugin. The Java plugin makes it easier to develop Java applications and provides features like compiling, code testing, Javadoc task, etc.

Furthermore, we’ll add code to the gradle.build file for the Javadoc task:

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

This configures the Javadoc task and specifies the build directory to store the generated documentation.

We can also configure the Javadoc task to include and exclude packages when running the task:

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

Here, we include the addition package and exclude the subtraction package. The include and exclude properties allow us to select the packages we want in the Javadoc task.

Finally, to generate the documentation, let’s open our terminal and change to the root folder. Then, let’s run the Gradle build command:

./gradlew javadoc

This command executes the Javadoc task and generates the documentation in the HTML format. The HTML files are stored in the specified folder.

Here’s an example of an HTML file documentation:

6. Conclusion

In this article, we learned how to generate Javadoc using the Gradle build system. Additionally, we saw how to write documentation comments for two Java classes. Moreover, we learned how to configure Javadoc to include and exclude packages.