Android documentation done right

Ink is better than the best memory. — Chinese proverb

Documentation is an important but scorned after part of a project. No matter how great you library works, a bad or scarce documentation often leaves a bad taste and could lead to poor developer acceptance.

Don’t document the program; program the document.

Java docs have long been used to provide clear and concise documentation for libraries and projects. But, as android development moved to Kotlin we need new tools. The language used to document Kotlin code (the equivalent of Java’s JavaDoc) is called KDoc. In its essence, KDoc combines JavaDoc’s syntax for block tags (extended to support Kotlin’s specific constructs) and Markdown for inline markup.

The documentation generation tool for Kotlin is Dokka. In this post we will see how to setup dokka in our android project.

Step 1 : Adding the dependency for dokka plugin

buildscript {
    repositories {
        jcenter()
    }

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

apply plugin: 'org.jetbrains.dokka'

The current version is 0.9.17 at the time of writing this post. The plugin adds a task named “dokka” to the project.

Step 2 : Configure the dokka task

dokka {
    outputFormat = 'html' 
    outputDirectory = "$buildDir/javadoc"
}

The tool supports a few different output formats :

• html - minimalistic html format used by default
• javadoc - Dokka mimic to javadoc
• html-as-java - as html but using java syntax
• markdown - Markdown structured as html
• gfm - GitHub flavored markdown
• jekyll - Jekyll compatible markdown
• kotlin-website - internal format used for documentation on kotlinlang.org, this does not generate plain htmls

I personally prefer the html format over the plain old javadocs.

Step 3 : Build dokka

./gradlew build

We can also build this from the gradle >tasks > documentation > dokka.

And we are done.