Introduction to KDoc

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:

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.