Introducing KDoc

If all that you want to do is add explanations to your code, to be read as part of that code, the comment syntax shown above is all that you need.

If you want to be able to generate standalone documentation for your code, the way that JavaDocs, RDoc, and similar tools do… Kotlin’s equivalent is KDoc.

Basic KDoc Comments

Once again, Kotlin uses Java’s approach and extends it. So, just as JavaDoc comments start with /** and end with */, so too do KDoc comments:

/**
 * This is the summary of your Kotlin class. It should explain, in a single
 * paragraph, the role of this class in your project.
 *
 * Additional paragraphs after the first one should explain your class in
 * greater detail. Of course, this class is extremely simple. It does not
 * need much in the way of explanation. Yet, for some reason, the author
 * insists on keeping on typing text into this paragraph, as if his hand is
 * guided by some unseen force. Or, perhaps, he is just trying to pad the
 * paragraph out a bit.
 *
 * Oh, by the way, the line of asterisks that you see on the left is optional,
 * as you will see in the function comment below.
 */
class Foo {

  /**
   This should explain what this function does.

   Um, that's it!
   */
  fun something() {
    println("Hello, world!")
  }
}

Formatting

Where KDoc breaks from JavaDoc is in terms of text formatting. KDoc uses Markdown, arguably the world’s most popular “wikitext” markup language. Everything from Stack Overflow questions to GitHub README files are written in Markdown. This book is written in Markdown. And KDoc lets you use Markdown formatting in your comments.

So, you can use things like:

**Boldface** (renders as: Boldface)
*Italics* (renders as: Italics)
Backticks wrapped around text to format it in monospace
And so on

Cross-Referencing

What Markdown lacks is a way to link to things inside the same document. Its hyperlink syntax works great for links to other pages, but not to material in the current page.

KDoc extends Markdown linking syntax, allowing you to reference properties, functions, and similar named things by using simple bracket syntax:

/**
 * This is the summary of your Kotlin class. It should explain, in a single
 * paragraph, the role of this class in your project.
 *
 * This class has a single function: [something].
 *
 * You can also link to other classes, such as [kotlin.String], using the
 * fully-qualified class name.
 *
 * And, of course, you can [link to external content](https://commonsware.com).
 */
class Foo {

  /**
   This should explain what this function does.

   This function is inside of [Foo], as you can tell by looking up a few lines
   from where you are reading right now.
   */
  fun something() {
    println("Hello, world!")
  }
}

Block Tags

As with JavaDoc, KDoc supports “block tags” for documenting sub-elements of class, function, etc. For example, you can use @param to document a function parameter, @return to document a function return value, and so forth:

/**
 * This is the summary of your Kotlin class. It should explain, in a single
 * paragraph, the role of this class in your project.
 *
 * This class has a single function: [something].
 *
 * You can also link to other classes, such as [kotlin.String], using the
 * fully-qualified class name.
 *
 * @author Mark Murphy
 */
class Foo {

  /**
   This should explain what this function does.

   This function is inside of [Foo], as you can tell by looking up a few lines
   from where you are reading right now.

   @param   msg the message to be printed
   @return  `true`, because, hey, why be negative?
   */
  fun somethingMoreElaborate(msg: String = "Hello, world!"): Boolean {
    println(msg)

    return true
  }
}

A complete list of block tags is available in the Kotlin documentation.

Generating the Documentation

Just as Java has a javadoc program to generate JavaDocs, and just as Ruby has rdoc to generate documentation from RDoc comments, Kotlin has a similar tool: Dokka.

Most likely, you will generate your documentation using the build system for your project, such as Gradle for an Android app project. There is a way to generate the documentation from the command line, though Dokka does not seem to be optimized for that use case.

Prev Table of Contents Next

This book is licensed under the Creative Commons Attribution-ShareAlike 4.0 International license.