KDoc in a Nutshell

okuzawats
okuzawats

What is KDoc?

KDoc is a documentation language for Kotlin. You can use KDoc in an Android project also. If you have already used JavaDoc, you can find it is the equivalent of JavaDoc in Java. You can markup KDoc using markdown, and can generate document with Dokka. If you’d like to know the syntax, please refer to the reference.

Example

Here is an example of KDoc. The code is from my private repository.

/**
 * A class that express app version.
 *
 * Create an instance from a string of x.y.z format with [fromRawString].
 * If you do [toString], itt will return a string in the format of [majorVersion].[minorVersion].[patchVersion].
 * This class implements [Comparable], you can compare between [Version]s.
 * In this case, it compares in order of [majorVersion], [minorVersion], [patchVersion].
 *
 * @property majorVersion The major version of the app.
 * @property minorVersion The minor version of the app.
 * @property patchVersion The patch version of the app.
 */
class Version private constructor(
    private val majorVersion: Int,
    private val minorVersion: Int,
    private val patchVersion: Int
): Comparable<Version> {
    // abbreviated
}

Why you need KDoc?

  • reducing learning costs
    • because you can write in a natural language
      • for newcomers to the project
      • or maybe for you in one month later
  • improving design quality
    • you can recognize design issues and omissions from consideration

What to write in KDoc?

  • specifications
  • how to use the codes
  • why is the code like that

It is important to write a KDoc in a way the code user would understand how to use it.

In my opinion, it is better to write a code according to the documentation comment, not to write a documentation comment according to a code.

What NOT to write in KDoc?

  • just a translation of the codes
    • don’t bother the readers with comments to codes that can be understood just reading
  • documentation comments to private methods
    • documentation comments should be on public APIs
    • if you want to comments on private methods, you can use normal comments

The content of this post is what I presented at YUMEMI.apk #1.