Dokka Alpha for Kotlin 1.4

Marina Shishkina

We’ve released Dokka (Alpha) on Kotlin 1.4! This release aligns Dokka with the latest stable version of the Kotlin compiler. It focuses on reducing the amount of configuration required to use Dokka in the most common cases – including Kotlin multiplatform projects – because spending less time writing Dokka configuration means more time to write Kotlin documentation!

We previously released Dokka on Kotlin 1.4.0-RC, where we redesigned many parts of our documentation engine from scratch, and introduced a number of new features and improvements, such as the new HTML format, multimodule projects, and pluggability.

Since then, we have also received a lot of valuable feedback from the community – from bug fixes to better source set grouping in multiplatform projects – which we incorporated into this release. Let’s take a look!

Simplified Gradle Plugin

With this version of Dokka, we continue with our efforts to make our Gradle plugin as easy to use as possible while still supporting all the advanced configuration that power users rely on. From now on, in fact, generating documentation through Dokka won’t require any manual configuration for most projects! Simply adding the Dokka Gradle plugin is already enough to cover all usual cases in build.gradle.kts:

    plugins {
       id("org.jetbrains.dokka") version “1.4.0”
    }

All the information about your project that is necessary to generate documentation, including information about your source sets, will automatically be kept in sync with the Kotlin Gradle plugin. Every source set that is registered or known to Kotlin will also automatically be available for further configuration in Dokka.

All that is left to do is to run the Dokka tasks (such as dokkaHtml or dokkaJavadoc) to generate documentation for your project. Of course, you can still apply further configuration settings to make Dokka meet your specific requirements, or make use of more advanced functionality.

We hope that by removing the need for a lot of manual configuration, and by improving the “auto-configuration” mechanism and making it more intuitive, we can make it easier for you to get started generating documentation with Dokka.

Multiplatform

The same default configuration introduced in the previous section also works well for multiplatform projects. Simply apply the Dokka Gradle plugin, and all platform-specific source sets will automatically be synchronized with the Kotlin model. There is no longer any need to register additional source sets in Dokka for most projects, which means redundant information can be removed from your configuration files.
For simple control over how different platforms are treated, we are also introducing a straightforward way to merge multiple source sets.

Merging source sets

By default, Dokka shows one “bubble” (platform marker) per source set in your project, which serves as a quick and easy way to filter documentation to the APIs available for a specific target. However, if you are working in a project with a lot of source sets, for example a Kotlin multiplatform project targeting a large number of native targets, this overview could quickly become cluttered. Consider this example from kotlinx-coroutines:

Previously, complicated configurations were necessary to group such related source sets together into a single “bubble”, which in turn introduced unnecessary complexity in the project build files.

Because we saw that community projects and official Kotlin projects alike demonstrate a significant need for this grouping functionality, we are introducing a new and vastly simplified mechanism to solve the merging of source sets. All source sets which represent the same platform (common, JVM, JS, or native) and have the same displayName will be merged into the same “bubble”.

For example, to group all native source sets together under the “native bubble”, you can now simply apply a configuration like this in build.gradle.kts:

tasks.withType<DokkaTask>().configureEach {
    dokkaSourceSets {
        configureEach {
            if (platform.get() == native) {
                displayName.set("native")
            }
        }
    }
}

After re-generating your documentation, you will have a much more concise list of source set “bubbles”:

We hope that this support for merging source sets will help you simplify your Dokka configuration, and remove the need for any workarounds that were previously required.

Compatibility and stability notes

Please note that Dokka for Kotlin 1.4.0 is an Alpha release. Gradle plugin APIs are subject to change in future Dokka releases.

Dokka for Kotlin 1.4.0 is integrated more tightly with the Kotlin Gradle plugin, and keeps the information about your configuration in sync. To facilitate these new integration mechanisms, we switched to Gradle’s new Provider and Property APIs, which required us to break the current configuration API. As a result, assigning values to properties is now done by using .set() instead of =, for example:

jdkVersion.set(8)

For a detailed overview of changes and improvements in the configuration DSL, including the long-awaited replacement of String based APIs with java.io.File based APIs, check out our migration guide.

How to try it

To use the newest version of Dokka in your project, add the corresponding plugin directive to the top of your build.gradle(.kts) file:

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

We hope that the features introduced with this version of Dokka make it even easier and more productive for you to create beautiful and easy to navigate documentation for your projects.

Continue helping us to improve Dokka!

We rely on your feedback to continue improving Dokka. If you encounter any problems, please report them on Dokka’s GitHub issue tracker. You can also join the conversation on the official Kotlin Slack in the #dokka channel.

We’d like to say a special thanks to everyone who shared their feedback and reported issues. We take your concerns and ideas to heart, and we are working hard to make Dokka the best possible documentation experience for Kotlin!

Subscribe to Kotlin Blog updates

Subscribe form

By submitting this form, I agree to the JetBrains Privacy Policy Notification icon

By submitting this form, I agree that JetBrains s.r.o. ("JetBrains") may use my name, email address, and location data to send me newsletters, including commercial communications, and to process my personal data for this purpose. I agree that JetBrains may process said data using third-party services for this purpose in accordance with the JetBrains Privacy Policy. I understand that I can revoke this consent at any time in my profile. In addition, an unsubscribe link is included in each email.

Submit

Thanks, we've got you!