Javadoc

Javadoc generates HTML pages of API documentation from Java source files, allowing you to leave comments at the method, class, and package levels.

There is detailed information about Javadoc on the Oracle documentation..

Run

$ ./gradlew build
$ ./gradlew bootRun

Contents

You can document class or method-level comments using Javadoc, and generate the documentation with the following commands:

/**
 * This class provides common API functionalities such as health checks.
 */
@RequestMapping(path = "/api")
@RestController(value = "javaCommonApi")
public class JavaCommonApi {

    /**
     * Health check endpoint.
     *
     * @return A ResponseEntity with an HTTP 200 status.
     */
    @GetMapping(path = "/health-check/v1")
    public ResponseEntity<Void> healthCheck() {
        return ResponseEntity.ok()
            .build();
    }
}

$ ./gradlew javadoc         # Java
$ ./gradlew dokkaHtml       # Kotlin

You can also leave package-level comments using package-info.java. package-info.java is a Java file that allows you to document or comment on the package level.

@NonNullApi
@NonNullFields
package project.io.app.core.user.application;

import org.springframework.lang.NonNullApi;
import org.springframework.lang.NonNullFields;

This file allows you to add comments or documentation for the entire package.

/**
 * This package contains user-related service implementations.
 * All parameters and return values are assumed to be non-null by default.
 */
@NonNullApi
@NonNullFields
package project.io.app.core.user.application;

import org.springframework.lang.NonNullApi;
import org.springframework.lang.NonNullFields;

However, caution is required when using this, as it is thoroughly explained in detail in the Oracle documentation.

The manner in which this restriction is enforced must, of necessity, vary from implementation to implementation. The following scheme is strongly recommended for file-system-based implementations: The sole annotated package declaration, if it exists, is placed in a source file called package-info.java in the directory containing the source files for the package. This file does not contain the source for a class called package-info.java; indeed it would be illegal for it to do so, as package-info is not a legal identifier. Typically package-info.java contains only a package declaration, preceded immediately by the annotations on the package. While the file could technically contain the source code for one or more package-private (default-access) classes, it would be very bad form.

To exclude specific packages or classes, you can configure it as follows to omit them from the documentation. When creating Javadoc for a project with module descriptors, the exclude method fails, causing Javadoc errors. You can manually set the source path and exclude specific packages as shown below:

tasks.withType<Javadoc> {
    (options as StandardJavadocDocletOptions).apply {
        encoding = "UTF-8"
        addStringOption("Xdoclint:none", "-quiet")
        addStringOption("html5", "-quiet")
    }
    
    val directories = sourceSets
        .main
        .get()
        .java
        .sourceDirectories
        .joinToString(":")
    (options as CoreJavadocOptions).addStringOption("-source-path", directories)
    exclude("**/response/**", "**/request/**")
}

tasks.withType<Javadoc> {
    (options as StandardJavadocDocletOptions).apply {
        encoding = "UTF-8"
        addStringOption("Xdoclint:all", "-quiet")
        addStringOption("html5", "-quiet")
    }

    ... ...

}

$ ./gradlew javadoc

> Task :javadoc
/Users/mac/jun/jun-labs/package-info/src/main/java/project/io/app/core/user/presentation/UserReadApi.java:21: warning: no comment
    public UserReadApi(final UserService userService) {
           ^
/Users/mac/jun/jun-labs/package-info/src/main/java/project/io/app/core/user/application/UserService.java:15: warning: no comment
    public void execute(final Long userId) {
                ^
2 warnings

If you are using Kotlin, you can write the code as follows:

tasks.dokkaHtml.configure {
    outputDirectory.set(layout.buildDirectory.dir("docs/dokka").get().asFile)
    dokkaSourceSets {
        named("main") {
            perPackageOption {
                matchingRegex.set(".*request.*")
                suppress.set(true)
            }
            perPackageOption {
                matchingRegex.set(".*response.*")
                suppress.set(true)
            }
        }
    }
}

Because of a version issue in Dokka, you need to add the following configuration:

configurations.matching { it.name.startsWith("dokka") }.configureEach {
    resolutionStrategy.eachDependency {
        if (requested.group.startsWith("com.fasterxml.jackson")) {
            useVersion("2.15.3")
        }
    }
}

Otherwise, you will encounter the following error message:

Execution failed for task ':dokkaHtml'.
> 'void com.fasterxml.jackson.databind.type.TypeFactory.<init>(com.fasterxml.jackson.databind.util.LRUMap)'

Javadoc is not automatically included in the build process.

4:56:27PM: Executing 'build'...

> Task :compileKotlin UP-TO-DATE
> Task :compileJava UP-TO-DATE
> Task :processResources UP-TO-DATE
> Task :classes UP-TO-DATE
> Task :resolveMainClassName UP-TO-DATE
> Task :bootJar UP-TO-DATE
> Task :jar UP-TO-DATE
> Task :assemble UP-TO-DATE
> Task :compileTestKotlin NO-SOURCE
> Task :compileTestJava UP-TO-DATE
> Task :processTestResources UP-TO-DATE
> Task :testClasses UP-TO-DATE
OpenJDK 64-Bit Server VM warning: Sharing is only supported for boot loader classes because bootstrap classpath has been appended
> Task :test
> Task :check
> Task :build

If you want to include it in the build process, you need to add the following dependency:

tasks.build {
    dependsOn("javadoc")
}