Documenting Kotlin Code Using KDoc and Dokka

KDoc is the language for documenting Kotlin code, and Dokka is the engine for generating documentation from KDoc. Dokka can generate documentation in pretty nice HTML format, as well as documentation in Javadoc, Gfm, and Jekyll formats. This article will introduce how to use KDoc and Dokka in a project.

The complete code for this chapter can be found in .

KDoc

KDoc is the language for documenting Kotlin code, just as Javadoc is the language for documenting Java code. KDoc combines Javadoc and Markdown. KDoc supports HTML tags because it inherits Javadoc syntax. Additionally, it also supports Markdown, which Javadoc doesn’t have. KDoc uses Javadoc’s block tags and adds several additional block tags.

The following example shows several commonly used block tags.

• @constructor: Document the primary constructor.
• @property: Document the property parameter in the constructor.
• @param: Document parameters passed in the constructor and function.
• @return: Document the return value.
• @throws, @exception: Document exceptions that will be thrown by the method. Since Kotlin does not have checked exceptions, it is not expected to document all exceptions that might be thrown.
• @see: See also block.
• @sicne: The version to start supporting.
• @receiver: Document the extension function.
• @suppress: Don’t export this function to the documentation.
• @Deprecated: Document this function as deprecated.

It is worth noting that KDoc does not provide a block tag to document properties in a class. This is because you only need to add a comment above the property without using any block tag.

/**
 * A group of *members*.
 *
 * This class has no useful logic; it's just a documentation example.
 *
 * @param T The type of a member in this group.
 * @property name The name of this group.
 * @param max The maximum number of total members.
 * @constructor Creates an empty group.
 */
class Group<T>(val name: String, max: Int) {
    /** All members */
    var members: List<T> = emptyList()
        private set

    /**
     * Adds a [member] to this group.
     * @param member The member to add.
     * @return The new size of the group.
     * @throws IllegalStateException If the number of the members is equal to the maximum.
     * @throws IllegalArgumentException If the given member does not have a name.
     * @see 1.0.0
     */
    fun add(member: T): Int { ... }

    /**
     * Search members in this group by a given name.
     * @param name The name to search.
     * @return All members that contains the given name.
     * @see add
     * @since 1.1.0
     */
    fun search(name: String): List<T> { ... }
}

/**
 * List all members' names containing the given name.
 * @receiver A string representing a name to search.
 * @return All members' names containing the given name.
 */
fun String.memberNames(): List<String> { ... }

Dokka

Dokka is an engine that generates documentation from KDoc, just like the Javadoc tool is a tool for generating documentation from Javadoc. Moreover, Dokka also supports generating documentation from Javadoc.

Dokka has two ways to generate documentation, one for single-module projects and one for multi-module projects.

Single-Module Project

Single-Module Project means that there is only one module in the project. First, add the following code to build.gradle at the project level. If yours is an Android project, you don’t need to add mavenCentral().

plugins {
    id "org.jetbrains.dokka" version "1.7.20"
}

repositories {
    mavenCentral()
}

Next, put the following code in build.gradle at the module level.

plugins {
    id 'org.jetbrains.dokka'
}

Finally, execute the following command under the project, and the documentation will be generated. By default, The documentation is output in build/dokka under the module. Dokka supports dokkaHtml, dokkaJavadoc, dokkaGfm and dokkaJekyll tasks to generate documentation in HTML, Javadoc, Gfm, and Jekyll formats, respectively.

AndroidDokkaExample % ./gradlew dokkaHtml

You can change the directory where the documentation is output. In build.gradle at the module level, set the directory for the documentation output. For more settings, please refer to the official website.

tasks.named("dokkaHtml") {
    outputDirectory.set(file("$rootProject.projectDir/docs/htmlMultiModule"))
}

Multi-Module Project

If the project has multiple modules, Dokka can combine these modules into one documentation. First, add the following code to build.gradle at the project level. If yours is an Android project, you don’t need to add it mavenCentral().

plugins {
    id "org.jetbrains.dokka" version "1.7.20"
}

repositories {
    mavenCentral()
}

Next, put the following code in build.gradle at the module level of each module.

plugins {
    id 'org.jetbrains.dokka'
}

The above settings are the same as the single module project. The difference is that the tasks we use are dokkaHtmlMultiModule, dokkaGfmMultiModule and  dokkaJekyllMultiModule.

AndroidDokkaExample % ./gradlew dokkaHtmlMultiModule

You can also change the directory where the documentation is output. In build.gradle at the project level, set the directory for the documentation output.

tasks.named("dokkaHtmlMultiModule") {
    outputDirectory.set(file("$rootProject.projectDir/docs/htmlMultiModule"))
}

If you want Dokka to exclude a module, you just don’t add org.jetbrains.dokka plugin to that module’s build.gradle.

Conclusion

The HTML-formatted documentation generated by Dokka is quite nice. KDoc inherits the familiar Javadoc syntax and also supports the easy-to-use Markdown. To me, this looks like a greatly upgraded version of Javadoc.