An Introduction to KDoc

1. Overview

KDoc is the official format for documenting Kotlin code. It’s an extension to Javadoc that supports Kotlin’s specific constructs.

In this tutorial, we’ll explore the fundamentals of KDoc, its benefits, and how to use it effectively. We’ll also look at some of the different ways to use KDoc to document Kotlin code.

2. Understanding KDoc

Fundamentally, KDoc merges Javadoc’s block tag syntax with Markdown’s inline markup approach.

Specific KDoc syntax is recognized by the Kotlin compiler which, along with Dokka, may be used to generate documentation in various formats. Most importantly, following KDoc’s syntax convention allows for a concise and apprehensible codebase by improving readability and enhancing collaboration between developers.

3. Using KDoc

Similar to Javadoc, KDoc comments are enclosed by /** and */ constructs and can have an asterisk at the beginning of each line without being treated as part of the comment’s content. As per convention, the initial paragraph of the documentation text until the first empty line serves as the summary description of the element, while the subsequent text provides a detailed description.

3.1. Example Class

Let’s look at a documentation example of a Blog class that has a single method for storing an article:

/**
 * A blog of *articles*.
 *
 * This class is just a **documentation example**.
 *
 * @param T the type of article in this blog.
 * @property name the name of this blog.
 * @constructor creates an empty blog.
 * @see com.baeldung.kdoc.TitledArticle
 * @sample com.baeldung.kdoc.blogSample
 */
class Blog<T>(private val name: String) {

    private var articles: MutableList<T> = mutableListOf()

    /**
     * Adds an [article] to this blog.
     * @return the new number of articles of the blog.
     */
    fun add(article: T): Int {
        articles.add(article)
        return articles.size
    }
}

/**
 * An article with a title.
 *
 * @property title the title of this article.
 * @constructor creates an article with a title.
 */
data class TitledArticle(private val title: String)

private fun blogSample() {
    val blog = Blog<TitledArticle>("Baeldung on Kotlin")
    val blogCount = blog.add(TitledArticle("An Introduction to KDoc"))
}

Notice that we can document both the class itself and its methods. The documentation also includes Markup elements for styling our documentation.

3.2. Block Tags

KDoc block tags start with the “@” symbol, followed by the tag name, and are placed above the code elements they describe. Let’s go through the most commonly used KDoc block tags:

• @param: describes a function or constructor parameter
• @return: describes the return value of a function
• @throws or @exception: documents exceptions that a function may throw
• @receiver: describes the receiver object of an extension function
• @property: documents a property of a class or interface
• @constructor: describes a constructor of a class
• @see: provides references to other elements, such as functions or classes
• @sample: embeds a code sample within the documentation
• @since: specifies the version that introduces the documented element
• @suppress: suppresses specific warnings for the documented element
• @author: identifies the author of the function or class

4. Conclusion

In this article, we’ve given an overview of the KDoc format for documenting Kotlin code. By combining Javadoc’s block tag syntax with Markdown’s inline markup approach, KDoc offers a concise and structured documentation format that is both developer-friendly and compiler-recognized.

With a wide range of block tags, KDoc enables comprehensive documentation that includes information about parameters, return values, exceptions, receivers, and more. It empowers us to write well-documented and maintainable code, which is accessible to both current and future contributors.