How to use Dokka Documentation Engine for Android Gradle App to generate KDoc or Javadoc comments

Table of Contents

• What is Dokka?
• Code
• Getting started
• Running Dokka
• What is KDoc or Javadoc?
• Custom output directory
• Separating the inherited functions
• Hiding deprecated functions
• Showing non-public members
• Uploading the Kotlin Dokka documentation online

What is Dokka?

Dokka is a tool to generate documentation based on the Javadoc or KDoc comments. It outputs the document generated in HTML, GitHub Flavored Markdown, or Javadoc format.

For example, it could be used to generate documentation for any Android app or library. In the image below, documentation is generated for the “Android Room with a View” Codelab App.

Code

https://github.com/androiddevnotesyoutube/android-dokka-documentation-kdoc

Getting Started

To get started, add the Dokka classpath to your project-level build.gradle file:

dependencies {
   
    classpath "org.jetbrains.dokka:dokka-gradle-plugin:1.4.30"
}

In your app-level build.gradlefile, add the Dokka plugin:

plugins {
    id 'com.android.application'
    id 'kotlin-android'
    id 'org.jetbrains.dokka'
}

The basic setup is done.

Running Dokka

To run Dokka to generate HTML, GFM (GitHub Flavored Markdown), Javadoc:

For Windows: use gradlew.bat

For Linux or Mac: use ./gradlew

Run: gradlew.bat dokkaHtml to generate HTML Docs.

Run: gradlew.bat dokkaGfm to generate GFM Docs.

Run: gradlew.bat dokkaJavadoc to generate Javadoc.

The generated docs are in your app\build\dokkadirectory.

Output:

What is KDoc or Javadoc?

Just like with Javadoc, KDoc comments start with /** and end with */. Every line of the comment may begin with an asterisk, which is not considered part of the contents of the comment.

To learn more about KDoc: https://kotlinlang.org/docs/kotlin-doc.html

To learn more about Javadoc: https://www.oracle.com/hk/technical-resources/articles/java/javadoc-tool.html

Custom output directory

In your app-level build.gradle file, add:

tasks.dokkaHtml.configure {
    outputDirectory.set(file("../documentation/html"))
}

The above code is tested on Windows OS and it works.

The output will be generated at documentation\html .

The Official Docs suggests using the below code which however did not work for me:

tasks.named("dokkaHtml") {
    outputDirectory.set(buildDir.resolve("dokka"))
}

Separating the inherited functions

In version 1.4.30 of Dokka, the generated functions also include inherited ones. This means even the function we did not override in the class, the docs for them are also unnecessarily generated.

This results in wastage of space and clutters the docs. This also makes it way harder to find our own documented functions among the hundreds of inherited functions.

There’s an open issue: https://github.com/Kotlin/dokka/issues/1501

The workaround for HTML is to separate the inherited functions into different columns.

To do that, in your app-level build.gradle file, add:

tasks.withType(dokkaHtml.getClass()).configureEach {
    pluginsMapConfiguration.set(
            ["org.jetbrains.dokka.base.DokkaBase": """{ "separateInheritedMembers": true}"""]
    )
}

To note, this only works with HTML. The GFM or Javadoc will still have all the inherited and the ones we defined in the class in the same column.

Functions vs Inherited Functions

There’s a good chance in the future the inherited functions will be hidden when not overridden in the class. The milestone is described here: https://github.com/Kotlin/dokka/milestone/21

Hiding deprecated functions

In your app-level build.gradle file, add:

dokkaHtml.configure {
    dokkaSourceSets {
        named("main") {
            skipDeprecated.set(true)
        }
    }
}

Showing non-public members

You most often want to show classes in the companion object in Dokka documentation. By default as of version 1.4.30, Dokka does not show that.

To show it, in your app-level build.gradle file, add this code configuration:

dokkaHtml.configure {
    dokkaSourceSets {
        named("main") {
            includeNonPublic.set(true)
        }
    }
}

Uploading the Kotlin Dokka Documentation Online

Go to your repository settings, scroll down to the GitHub Pages section, select main or whatever your branch name is, and click save.

Done!

The documentation for the code used in this example: https://androiddevnotesyoutube.github.io/android-dokka-documentation-kdoc/documentation/html/navigation.html

Output:

Dokka documentation online

Code: https://github.com/androiddevnotesyoutube/android-dokka-documentation-kdoc

On an ending note, there’s a lot of configuration options listed here: https://kotlin.github.io/dokka/1.4.30/user_guide/gradle/usage/#configuration-options

However, some of these options as of version 1.4.30 does not work as advertised.

References

Official docs for Gradle: https://kotlin.github.io/dokka/1.4.30/user_guide/gradle/usage/

Official GitHub repo: https://github.com/Kotlin/dokka

Find us at

Discord: https://discord.gg/7BgVnSb3SF

GitHub: https://github.com/androiddevnotes/

YouTube: https://www.youtube.com/channel/UCQATLaT0xKkSm-KKVQzpu0Q

Twitter: https://twitter.com/androiddevnotes

Instagram: https://www.instagram.com/androiddevnotes

Contributions

Contributions and Pull requests are welcomed at https://github.com/androiddevnotes repositories!

🐣