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.
