PSA Java Developers: Use Dokka in Addition to Javadocs

Use Dokka.md

What's Dokka?

Dokka is like Javadocs but with a much nicer frontend, with multiple export options (HTML, Markdown, etc), and with Kotlin support, if you need it. Just to clarify, it can be used in a pure Java project all the same. You can take a look at the Dokka project here.

How Do They Compare?

Take a look for yourself. I recently forked and published a project and I provide both Javadocs and Dokka. As you see, they both supply the exact same information, but one looks like this:

While the other looks like this:

Yeah... I think I know what I'd rather look at during a late night coding session.

How Do I Set up Dokka?

In your gradle/libs.versions.toml add the following:

[versions]
# Check this on https://github.com/Kotlin/dokka/releases/latest/
dokka = "2.1.0"

[libraries]
dokkaJavaPlugin = { group = "org.jetbrains.dokka", name = "kotlin-as-java-plugin", version.ref = "dokka" }

[plugins]
dokka = { id = "org.jetbrains.dokka", version.ref = "dokka" }

In your build.gradle.kts add the following:

plugins {
    `maven-publish`
    alias(libs.plugins.dokka)
}
repositories {
    mavenCentral()
}
dependencies {
    // This is what makes Dokka display Java signatures instead of Kotlin signatures.
    dokkaPlugin(libs.dokkaJavaPlugin)
}
// The following is optional. It'll generate a jar with Dokka documentation packaged into it, like the Javadoc jar.
tasks {
    register<Jar>("dokkaJar") {
        group = JavaBasePlugin.DOCUMENTATION_GROUP
        dependsOn(dokkaGenerateHtml)
        archiveClassifier = "dokka"
        from(layout.buildDirectory.dir("dokka/html"))
    }
    named("build") {
        dependsOn(named("dokkaJar"))
    }
}
// If you want to ship it in your publication you would do this:
publishing {
    publications {
        create<MavenPublication>("maven") {
            // ...
            artifact(tasks.named("dokkaJar"))
            // ...
        }
    }
}

That's it! Now you can simply run the dokkaGenerateHtml Gradle task to generate your Dokka HTML for your library.

How Do I Easily Deploy Dokka to GitHub Pages?

Add this .github/workflows/publish-dokka.yml file:

name: Publish Dokka to GitHub Pages

on:
  release:
    types: [published]

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Validate Gradle Wrapper
        uses: gradle/actions/wrapper-validation@v5

      # Modify this as needed.
      - name: Set up Java
        uses: actions/setup-java@v5
        with:
          distribution: temurin
          java-version: 21
          cache: gradle

      - name: Make Gradle wrapper executable
        run: chmod +x gradlew

      - name: Build Dokka HTML
        run: ./gradlew dokkaGenerateHtml

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v4
        with:
          path: build/dokka/html

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

Now whenever you create a new release for your project on GitHub, the repository's GitHub Pages will be updated. This is what I do on this project of mine.