KDoc and Dokka

This page describes only documentation aspects of programming in Kotlin. For general conventions please see Kotlin code style.

Please use these guidelines for Android developers as general rules. Recommendations and requirements specific to Spine SDK are described below.

Dokka in multi-module projects

Dokka works differently in single- and multi-module projects. Things to remember for multi-module project:

1. Apply the Dokka plugin to the root project and subprojects.
2. The task which creates the documentation for submodules has the type DokkaTaskPartial.
3. The task which gathers HTML documentation in the root of multi-module project has the type DokkaMultiModuleTask.

Configuring tasks in modules

tasks.withType<DokkaTaskPartial>().configureEach {
    configureForKotlin()
}

where configureForKotlin() is the extension from buildSrc/DokkaExts.kt.

Configuring root project task

val dokkaHtmlMultiModule by tasks.getting(DokkaMultiModuleTask::class) {
    configureStyle()
}

where configureStyle() is the extension from buildSrc/DokkaExts.kt.

Documenting a type

When describing a type, such as class an interface, document all the parameters and properties using tags @param and @property. Please use the following order:

1. Generic parameters. Document all of them, including those inherited from a super-type. Unlike inherited properties, Dokka does not list inherited generic parameters. And this is for a reason, a sub-type may narrow down the inherited parameter, and therefore its description is likely to change.

2. Parameters and properties in the order they are passed to the constructor. Do not group them by kind. They are grouped by Dokka when rendering the docs. Following the order of descriptions after the code makes it easier to find the docs when reading the code. Correspondingly, if you change the order of parameters when refactoring, please do not forget to update the order of their documentation.

Layout of descriptions

Unlike in Java, we cannot put the description of a parameter on the next line below its name. Such a layout is not fully "understood" by IDEA. It won't recognise links to other types or properties, for example. We have to do it like this:

/**
 * ...
 *
 * @param L The type of the programming language served by this action.
 * @param D The type of the Protobuf declaration, such as
 *   [MessageType][io.spine.protodata.MessageType], [EnumType][io.spine.protodata.EnumType] or
 *   [Service][io.spine.protodata.Service], for which this action generates the code.
 * @param P The type of the parameter passed to the action.
 *   If the action does not have a parameter, please use [com.google.protobuf.Empty].
 *
 * @param language The language served by this action.
 * @property subject The Protobuf declaration served by this action.
 * ...
 */

Please note an empty line between the section of generic parameters and parameters and properties passed to a constructor.

Start a description with a capital letter, as for a sentence. You may find contrary examples in Kotlin code or even in KDoc examples, but it's not the way it is supposed to be if you look at the rendered documentation. These descriptions come as separate blocks of texts and are presented as sentences, not fragments as in Javadoc.

Also, a capital letter separates the description text better and gives you more freedom of writing as an author.