Dokka Preview Based on Kotlin 1.4.0-RC
The following post is written by Paweł Marks and Kamil Doległo.
Every programming ecosystem needs documentation to thrive. Kotlin has its roots in the JVM ecosystem, where Javadoc is a standard and universally accepted documentation engine. It was only natural to expect Kotlin to have a similarly seamless tool. That was the initial goal of Dokka – to provide a reliable and simple documentation engine. But the increasing diversity of Kotlin, with features like multiplatform projects, Native support, and so on, requires Dokka to be more complex.
The ongoing development of Kotlin 1.4 gave us a chance to rethink, redesign, and reimplement Dokka from scratch (its version number is now aligned with the Kotlin embedded compiler). In this post, we give you an overview of Dokka’s new features and announce its preview release. We would appreciate it if you could try the preview and share your feedback.
How to Try
Dokka is distributed as a plugin for two of the most popular Kotlin build tools – Maven and Gradle. For advanced use cases, Dokka can be used as a standalone command-line application. For a Gradle-based project, just add the following to your project’s build.gradle or build.gradle.kts files:
plugins {
id("org.jetbrains.dokka") version "1.4.0-rc"
}
repositories {
jcenter()
}
After running ./gradlew dokkaHtml you should see generated documentation in the dokka directory inside your project’s build directory.
New HTML format
One of our main goals was to produce good-looking, modern documentation without any need for tweaking and configuration from the user. That is why the default look of Dokka is no longer a simple static web page. Let’s take a quick look at the most important features of the new HTML format. Note that we’ve used the coroutines documentation to demonstrate the new Dokka format, but we won’t actually be converting this documentation until a later time.
Navigation tree
On the left side of your screen, you can see all your project modules, packages, and types organized in a hierarchical menu. This allows you to not only see the project structure at a glance, but also to quickly navigate between different parts of your codebase.
Search bar
If your project is particularly complex, or you don’t know its codebase structure and you need to find some type or function, you can use the built-in search bar. It knows all symbols in the project so it can offer IDE-like autocompletion for search queries.
Linking to sources
Dokka can link from any symbol to its definition in code if your project’s code is hosted online. Just configure your repo URL using the sourceLink option as a generation parameter and all your functions and types will get links pointing to the exact line of code where each of them was defined.
Information about platforms
Kotlin is a multiplatform language and its documentation engine needs to reflect all platform information that can be important for end-users. In the documentation for a multiplatform project, you will notice that every symbol is marked with a badge indicating to which platform it applies. Moreover, if there are any differences between documentation or signatures of the same symbol on different platforms you can use the tabs to switch between them.
On every page you can choose to show or hide symbols defined in specific platforms.
Runnable samples
Kotlin has a great tool called Kotlin Playground that allows you to run simple code snippets from your browser. This tool is now also integrated with Dokka. You can specify the source of your samples and they will be included in your documentation, allowing end users to check how to properly use your library. All you have to do is create an ordinary Kotlin file with your code, include it in the documentation using
samples = listOf(<paths to the files>)
and link to the desired method using
@sample <fully qualified name of your method>
and Dokka will automatically copy the source code and use it to create a runnable block.
Other formats
Markdown
If you want to host your documentation on GitHub pages or other sites that use markdown formatting, Dokka has that covered. Out of the box, it supports two different flavors of Markdown – Jekyll and GFM (GitHub Flavored Markdown). To use them you only need to run dokkaJekyll or dokkaGfm task.
Kotlin-as-java and javadoc
Kotlin is interoperable with Java, which means that Kotlin libraries that target the JVM can be used from Java projects. Dokka can generate documentation for them too. You just need to include dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.4.0-rc") for HTML format or dokkaGfmPlugin(...) or dokkaJekyllPlugin(...) for GFM and Jekyll formats respectively. You will see your classes and functions in a Java-like format, for example, class properties will be changed to the appropriate get and set methods. Thanks to our new architecture, the Kotlin-as-java plugin works with HTML, GFM, and Jekyll Markdown, as well as some user-defined formats.
You can go one step further and not only desugar your properties to getters and setters but also generate documentation in the same way as Javadoc does. You just need to run the dokkaJavadoc task. The new Javadoc generation is completely independent of JDK artifacts, so it is guaranteed to work with every modern version of JDK (8 and newer).
Multimodule projects
By default, Dokka generates one set of documentation per Kotlin module.
- Run the
dokkaHtmlCollectortask to collect all definitions for all modules and document them as if they were a single module. This way the code can be divided into small modules while still having one documentation set. - Run the
dokkaHtmlMultimoduletask to generate documentation for each module in a separate directory and then create a common page with an index that links to all modules with brief previews of their documentation. You can customize this page by providing your own template in a Markdown file.
Other features
Even though Dokka 1.4 is completely rewritten, we wanted to preserve all the useful features and configuration options from previous releases. You can still:
- Generate documentation for mixed Java and Kotlin sources.
- Include Markdown documentation for the project, module, and package pages.
- Generate documentation for non-public symbols.
- Receive a report after generation about each undocumented symbol.
- Specify all generation options on a per-package basis.
Pluggability
The new Dokka has a flexible and powerful plugin system. Jekyll, GFM, kotlin-as-java, and Javadoc are only a few examples of plugins that can be created for the new Dokka. Everyone can now provide a custom format or transform the documentation in any way imaginable. Thanks to its robust framework it is intuitive to use and hard to accidentally break something. If you are interested in plugin development, check out our developers’ guide.
Subscribe to Kotlin Blog updates
