Two Developer Tools for Documenting Android Codebases

Documenting an Android project is easy, or is it?

Photo by Sigmund on Unsplash

Why?

So I maintain my company’s codebase, which is so much fun to do but also quite difficult. It’s hard because at the start, the code is small and you can learn it in a short time. Later on, the codebase is so huge (still monolith, not modular yet) and it’s not getting easier to keep track all of those code.

Of course, we’re starting to modularize the codebase, but it’s making it harder for new developers from the company to contribute and improve the codebase because the code is separated into modules, and no one knows where this part of code is located unless of course the people that modularize it.

From that, I always thought documenting a project is important. Why? Because it’s leaving a legacy for developers that come after us. It’s inviting the other developers to learn from it, and it helps a lot when you’re trying to refer to your old code.

“Good code documents itself”

Developers throw that quote around when talking about documentation. But I still think even with the well-thought naming convention, there’s a lot of things that can not you put in naming alone like context or reasoning why the code the way it is. So don’t be shy to document your code, trust me! It works.

KDoc

If you keep up to date with the trend, you probably using Kotlin for developing Android applications. Just like Java, there’s also a language to document Kotlin code and it’s called KDoc.

Here’s a snippet of how it’s done using KDoc:

Example using KDoc

TL;DR, use annotation tag inside a comment to explain part of your code. If you already familiar with Javadoc, writing KDoc is super easy… Barely an inconvenience.

The other thing you might want to do is document the packages, by creating a markdown file (commonly at the root of your module). That will look something like this:

Using KDoc to document packages

Dokka

You might call it a day after documenting all of your code with KDoc, but there’s always something more that you can do. So what is Dokka? It’s basically a documentation engine that will convert your KDoc comments into a shareable format like website or markdown file.

Here is the output format of Dokka:

• html , a static website that you can deploy anywhere
• gfm , Github flavored Markdown
• jekyll , Jekyll compatible Markdown
• javadoc , looks like Javadoc and convert your Kotlin code to Java

Dokka has a Gradle plugin that you can add to your Android project, more about that here.

I’ve tried all the output, but I can say html is only one worth using for now. Initially, I really want to use gfm because my codebase documentation is using Mkdocs to convert Markdown file to static website and to deploy it.

There are things like initial configuration, infrastructure, and all of that outside of the code documentation. By writing it in Markdown, it is easier because then we can just embed the formatted KDoc using Dokka as markdown to the Mkdocs directory.

After that, Mkdocs will convert all the markdown files as a website and the code documentation will have the same behavior and look like the rest of the documentation.

But there are bugs in gfm and jekyll format that I can say it’s not worth using. For example, here is the generated markdown from Dokka:

Modules documentation

Did you see the problem? Well let’s take a look:

• The table doesn’t have the second column called Summary
• The link of each module refers to the HTML file, not MD file

You might say, well, It’s just two right? right?? Well, there’s another:

Presentation module documentation

The same bug still appears in other files, and to reformat all the files is such a hassle and needs a lot of work to automate.

Furthermore, there are some Dokka features that don’t support in gfm format, like:

• Source link, where it can link your documentation to your file in the repository. It is only supported in html format.
• Code highlight, there’s no Kotlin highlighting in gfm format. But it supported in htmlformat.

There are some developers that contributed for a better gfm format, but I guess their main focus now is html format.

Don’t get me wrong, their generated HTML files are actually good, that’s why I’m using it for my codebase. In the end, the code documentation looks something like this:

Sample class from the codebase’s documentation

Tips

If you’re interested in using Dokka, here are some tips from me:

DokkaTaskPartial and DokkaMultiModuleTask

If your project is multi-module project, try using DokkaTaskPartial and DokkaMultiModuleTask when configuring your task. Like this:

Configuration for Dokka task

It helps you not define configuration for each output format, cause it automatically works for all formats.

Overriding copyright and icon

When using html format, probably you would change the copyright at the bottom of the website and the icon. First, add dokka-base plugin to your Android project, and configure pluginConfiguration in your build.gradle.kts module, like this:

Overriding configuration in Dokka

Make sure you are naming customAssets file with the same name as the automated generated asset file from Dokka.