Documenting Kotlin Code for Android Using KDoc and Dokka

Good documentation can make a developer prefer one library over others.

Documentation comes in many forms. From simple comments that live alongside the code to complex websites like the Android Developer documentation that cover things like platform APIs, build tools, samples, etc., it’s all documentation.

In this article, you’ll learn:

• How documentation can help you to improve the quality of your projects.
• To use KDoc to document your Kotlin code.
• To use Dokka to generate great-looking documentation quickly and easily.
• How to customize Dokka to your liking.

You’ll work on an Android library project called notktx and generate customized documentation for it.

The major target audience for libraries is usually other developers, so documenting a library project can be a great way to understand how to go about documenting codebases. Making it easy for other developers to use your project is a challenging but rewarding task — and good documentation plays a major role in it.

By the end of this article, you’ll have documentation generated in HTML for the notktx project. Here’s what it will look like:

This article assumes you have previous experience developing for Android in Kotlin. If you’re unfamiliar with Kotlin, take a look at this Introduction to Kotlin for Android article. If you’re also new to Android development, check out these Getting Started With Android tutorials.

Getting Started

Download the starter project by clicking the Download Materials button at the top or bottom of the tutorial.

Open Android Studio and click Open an existing Android Studio project.

Navigate to the starter project directory you downloaded and click Open.

Take some time to familiarize yourself with the project.

Understanding the Project Structure

The project implements extensions for Android widgets to help users by handling boilerplate code for various use cases.

You’ll find these three modules in the starter project:

1. app: An app module that shows sample usage of the library.
2. core: A library module that provides extensions for Android framework-related APIs and widgets.
3. utilities: Another library module that provides extensions that use third-party libraries to work.

Now that you have an overview of the files in this project, build and run. You’ll see a screen like this:

Making a Case for Documentation

Without realizing it, you might already be documenting your code. The code snippets below show different ways to write an Extension Function for SharedPreferences to add key-value pairs and commit the changes.

inline fun SharedPreferences.edit(ca: SharedPreferences.Editor.() -> Unit) {
  val e = edit()
  ca.invoke(e)
  e.commit()
}

//vs

inline fun SharedPreferences.editAndCommit(action: SharedPreferences.Editor.() -> Unit) {
  val prefsEditor = edit()
  action.invoke(prefsEditor)
  prefsEditor.commit()
}

Choosing descriptive names for variables and functions is the first step toward a well-documented codebase. In the example above, it’s much easier to understand what’s going on in the second function than in the first one.

You can go even further and add comments describing the function. For example:

/*
 * An extension function on SharedPreferences receiver type.
 *
 * It uses commit to persist the changes and invokes
 * action lambda function on the editor instance before committing.
 */
inline fun SharedPreferences.editAndCommit(action: SharedPreferences.Editor.() -> Unit) {
  val prefsEditor = edit()
  action.invoke(prefsEditor)
  prefsEditor.commit()
}

When you document your code, you help new users and contributors to trust and understand your project better. In a professional setting, good documentation helps new developers on your team — as well as on other teams — to get started with your project quickly.

Documentation also helps you. Going through your old codebase line by line after some time away can be time-consuming. So by documenting it, you’re helping your future self, too.

Going Beyond Code Comments

Documentation doesn’t have a fixed definition — but it goes way beyond comments. You can get as creative as you want while documenting your code, as long as it helps others to understand your code.

There are many ways to document a project:

• Hosting API references online.
• Writing a small book to give users an overview.
• Recording screencast videos walking users through major parts of the code.
• …and the list goes on.

Learning From Examples

In the Android world, Glide and Retrofit are quite famous for loading images and making network calls — and their documentation pages are really good.

Both of them try to get readers started as quickly as possible with minimal setup, but they provide in-depth API references for the advanced readers, too.

Golang and Kotlin provide code playgrounds to let users directly interact with sample programs. Check those out here and here.

Another super-creative example of documentation is this YouTube channel by Andreas Kling. He regularly uploads screencasts about his project SerenityOS.

All that to say, there isn’t just one way to define documentation. In the next few sections, you’ll see how to use KDoc and Dokka to ease the process of generating documentation for your Kotlin/Java/Android projects.

Introducing KDoc

If you’re coming from a Java background and have used JavaDoc before, you’ll feel right at home with KDoc. It uses JavaDoc’s syntax and adds support for Kotlin-specific constructs.

For those who haven’t used JavaDoc before, it’s a tool by Oracle that generates HTML pages from the Java source code files. The language format it uses for documenting is also named JavaDoc.

JavaDoc parses the source files for class/method declarations along with the comments written in JavaDoc format to add descriptions for those elements.

KDoc uses JavaDoc’s syntax, but unlike JavaDoc, it isn’t a tool to generate the HTML pages. Dokka generates the documentation from KDoc comments.

Open MainActivity.kt in the starter code and replace TODO:1 with the code snippet below:

/*
  Initializes the image loading sample views
  This demonstrates a plain multiline comment
*/

Also, replace TODO:2 with this snippet:

/**
 * Initializes the toast related views
 */

The first snippet is a plain multiline comment, and the second one is a KDoc documentation comment. It uses a forward slash followed by two asterisks instead of one.

Each line of a KDoc comment other than the first and the last one starts with an optional asterisk. Dokka ignores those asterisks.

Dokka recognizes KDoc comments only when they come immediately before a class/method/field definition — so they’re ignored when placed inside the body of a method or anywhere else.

The format of a KDoc comment consists of an initial description followed by a series of block tags. You’ll learn about the block tags in the next section.

The first paragraph of any KDoc comment before a blank line is the summary description of the element, and the text that follows is the detailed description.