Dokka: the Kotlin API documentation engine, and when it is the wrong tool

What Dokka solves, and who ends up using it

Kotlin has no javadoc tool. The JDK ships a doclet-driven generator that reads Java sources and Javadoc comments, and it does not parse KDoc or Kotlin's type system. Without a replacement, a Kotlin library's reference documentation has to be written by hand, which drifts from the code the moment a signature changes. Dokka fills that gap: it is an API documentation engine for Kotlin that understands KDoc comments and Java's Javadoc comments in the same run, so a mixed-language module produces one set of pages.

The audience is library and framework maintainers, not application teams. The README lists kotlinx.coroutines, Ktor, OkHttp, Gradle and Bitmovin among libraries that publish API reference with Dokka. That is the shape of the typical user: a project with a public API surface, a build it already runs in CI, and a need for browsable reference pages rather than prose guides. If your code is internal and nobody outside the team reads its signatures, the generated output has little audience.

How the Gradle plugin turns sources into pages

Dokka is not a single binary that walks a directory. It ships as build-tool integrations (a Gradle plugin, a Maven plugin, and a command line runner) plus a set of subprojects under dokka-subprojects/ that provide the actual parsing and output work. The repository layout reflects this: dokka-runners/ holds the entry points for each build tool, dokka-subprojects/ holds the engine and the format plugins, and dokka-integration-tests/ exists to exercise the combination.

The data flow is the part worth understanding before you wire it in. The build tool hands Dokka the compiled classpath and source sets rather than raw files, so Dokka resolves types through the same compiler infrastructure the Kotlin build already uses. That is why a multi-project Gradle build needs the plugin applied in subprojects as well as the root: each subproject contributes its own sources and dependencies, and the root aggregates them into one output. The README is explicit about the split, with dokkaHtml for single-project builds and dokkaHtmlMultiModule for multi-project builds, writing to /build/dokka/html and /build/dokka/htmlMultiModule respectively.

Output format is a plugin concern, not a core one. HTML is the default and the recommended format. Markdown comes in GitHub Flavored and Jekyll compatible variants, and Dokka can also emit a Javadoc HTML lookalike. The README states that both Markdown and Javadoc formats are still in Alpha, so bugs and migration issues are expected there. Treat that as a real constraint rather than boilerplate: if your publishing pipeline consumes Markdown, you are building on the least settled part of the tool.

Installing Dokka and generating your first HTML reference

The documented path is the Gradle plugin, applied in the root build script. The version in the README example is 2.2.0, which matches the v2.2.0 release listed for this repository. Add the plugin id and version to your plugins block:

plugins {
    id("org.jetbrains.dokka") version "2.2.0"
}

If your build is a multi-project build, the README says the plugin must also be applied within subprojects, otherwise the aggregated output will be missing their sources:

subprojects {
    apply(plugin = "org.jetbrains.dokka")
}

Then run the task for your build shape. For a single project the task is dokkaHtml; for a multi-project build it is dokkaHtmlMultiModule.

./gradlew dokkaHtml

By default the output lands in /build/dokka/html for the single-project task and /build/dokka/htmlMultiModule for the multi-module one. Open the index page in that directory to see the generated reference. Nothing else is required to get a first result; styling, footer text, custom assets and template changes are separate configuration covered in the HTML format documentation.

Maven users take a different route. The README's POM snippet binds the dokka-maven-plugin to the pre-site phase with the dokka goal, and running the dokka:dokka goal writes to target/dokka by default. The command line runner exists too, but the README declines to walk through it, saying it is more difficult to set up and pointing at the CLI documentation instead. That is a fair signal about where the project expects most people to live.

The Alpha formats are the real limitation

The strongest warning in the README is not about installation. It is that Markdown output (both GitHub Flavored and Jekyll compatible) and the Javadoc HTML format are Alpha, with bugs and migration issues to expect. HTML is the only format described as default and recommended. For a team whose docs site is built from Markdown files in a repository, or whose downstream tooling expects Javadoc-shaped HTML, this changes the calculus: you are adopting the supported engine to use its least supported output.

There is a second boundary. Dokka generates API reference from comments in source. It is not a documentation site generator for tutorials, migration guides or conceptual pages, and the README does not present it as one. Projects that need both usually run Dokka for the reference section and something else for everything written by hand.

The command line runner is a third friction point. It is documented as existing, but the README explicitly leaves setup out of scope because it is harder to configure than the build-tool integrations. Anyone planning to run Dokka outside Gradle or Maven should read the CLI documentation before assuming it is a drop-in equivalent.

Finally, note the stability badge at the top of the README: Dokka is marked Beta against Kotlin's component stability levels. That is a statement about the project's own confidence in its API surface, and it is worth weighing if you plan to depend on plugin internals rather than just the documented tasks.

Dokka against the JDK's javadoc tool

The obvious alternative is the JDK's javadoc tool. The difference is not cosmetic. Javadoc parses Java sources and Javadoc comments; it does not read KDoc, and it does not understand Kotlin declarations such as extension functions, coroutines or nullability in the type system. Dokka was built because Kotlin needed a generator that does, and the README frames its mixed-language support as the point: it understands both KDoc and Javadoc comments in one project.

Dokka's Javadoc output format is a deliberate concession to the other side of that comparison. It tries to visually mimic pages produced by the Javadoc tool, which is useful when consumers expect that layout. But the README places this format in Alpha, whereas javadoc is a long-shipped part of the JDK. So the trade is: Dokka gives you Kotlin-aware parsing and a Javadoc-shaped output that is less settled, while javadoc gives you a stable output that cannot see Kotlin at all. For a pure Java project, javadoc remains the simpler answer.

Maintenance, plugin versions and the licence

The repository is not archived, and the last push was on 2026-09-23. The most recent release listed is v2.3.0-Beta from 2026-09-15, with v2.2.0 from 2026-03-26 as the last stable version named in the README's examples. The README's own examples pin 2.2.0, so the stable line and the beta line are visibly separate. If you pin a version in your plugins block, check that the artifact resolves from Maven Central or the Gradle Plugin Portal, since the README badges both as distribution points.

Upgrade cost is mostly the usual build-plugin cost: a version bump in the plugins block or the POM, then a re-run of the dokkaHtml or dokka:dokka task and a look at the diff in generated output. The Alpha formats carry more risk here, because the README's warning about migration issues implies that output can change between versions in ways that affect downstream consumers of Markdown or Javadoc-shaped files. HTML output is the safer thing to depend on.

Dokka is licensed under Apache-2.0, and the repository carries both LICENSE.txt and NOTICE.txt at the top level. Apache-2.0 is a permissive licence that permits commercial use and modification, and it includes a patent grant. The NOTICE file matters if you redistribute Dokka or a derivative: Apache-2.0 requires that attribution notices be preserved. This is a description of the licence text, not legal advice; have your own counsel review anything you redistribute.

Editorial conclusion

Adopt Dokka if your API surface is Kotlin or mixed Kotlin/Java and you already build with Gradle or Maven, because the plugin attaches to a build phase you already run. Do not adopt it if you need stable Markdown or Javadoc output today, since the README marks both as Alpha, or if you only need hand-written guides rather than generated reference pages. Before committing, verify the Markdown and Javadoc output against your own sources and confirm the plugin version you pin matches the one your build resolves.

Frequently asked questions

Official sources

1. Kotlin/dokka on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases