Introduction to KDoc

September 23, 2023
- Kotlin

Table Of Contents

In this article, we’ll discuss all that entails KDoc in Kotlin. KDoc is simply a language used to document code written in Kotlin specifically. KDoc allows us to provide documentation comments for classes, functions, properties and other elements in our code. It’s the same as Javadoc which is used to document JAVA language. Essentially, KDoc combines syntax in Javadoc for the block tags and markdown for inline markup.

KDoc Syntax

Same as javadoc, KDoc comments usually start with /** and end with */.

Let’s see an example of KDoc:

/**
 * Calculates the sum of two numbers.
 *
 * @param a The first number.
 * @param b The second number.
 * @return The sum of the two numbers.
 */
fun sum(a: Int, b: Int): Int {
    return a + b
}

KDoc in our example is written above our sum function. In this case, KDoc explains what task our function performs and also documents the parameters a and b which the function takes inclusive of the expected return value.

Note that, different from JavaDoc, KDoc supports Markdown syntax.

KDoc Block Tags

Block tags are used to provide documentation for larger sections of code or to describe multi-line content within KDoc.They are usually placed on separate lines.

These are the block tags supported by KDoc:

Tag	Description
@param	This tag is used to document a value parameter of a function
@return	Used to document the return value of a function
@constructor	Used to document the primary constructor of a class
@receiver	Documents the receiver of an extension function
@property	This tag is used to document the property of a class that has the specified name
@throws,@exception	Used to document exceptions that can be thrown by a method
@sample	Used to embed the body of a function that has the specified qualified name
@see	Used to add a link to a specific class or method
@author	Used to specify the author of the element that is being documented
@since	Used to specify the version of the software in which the element under documentation was introduced

KDoc does not support the @deprecated tag. Instead, please use the @Deprecated annotation.

Code block example with block tags supported by KDoc:

/**
 * A list of movies.
 *
 * This class is just a **documentation example**.
 *
 * @param T the type of movie in this list.
 * @property name the name of this movie list.
 * @constructor creates an empty movie list.
 * @see https://en.wikipedia.org/wiki/Inception
 * @sample https://www.thetoptens.com/movies/best-movies/
 */
class MovieList<T>(private val name: String) {

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

    /**
     * Adds a [movie] to this list.
     * @return the new number of movies in the list.
     */
    fun add(movie: T): Int {
        movies.add(movie)
        return movies.size
    }
}

/**
 * A movie with a title.
 *
 * @property title the title of this movie.
 * @constructor creates a movie with a title.
 */
data class Movie(private val title: String)

private fun movieListSample() {
    val movieList = MovieList<Movie>("My Favorite Movies")
    val movieCount = movieList.add(Movie("Inception"))
}

Conclusion

In this article, we discussed KDoc which is the documentation language for Kotlin code. We also went through the KDOc’s syntax and the various tags it supports.

Written By: