Adding documentation to a kotlin project with Dokka

Dokka is for kotlin what Javadoc is for Java. It converts your KDoc-styled comments into a variety of document format such as HTML, Markdown (Github and Jekyll forms) and Javadoc HTML.

How to add dokka to your gradle project

Adding dokka to your Gradle project is very easy, as discussed in their documentation. You just add the dokka plugin to the plugins block of your module’s build gradle (not the root build.gradle file):

plugins {
    id "com.android.library"
    id "kotlin-android"
    id "org.jetbrains.dokka" version "1.4.32"
}

and that’s about it. The plugin will create several dokka-prefixed gradle tasks, each of which is responsible for generating the documentation in each of the supported formats.

Customising the dokka configuration

You can tweak the configuration of each documentation task by adding the corresponding dokka-prefixed block in your module’s build.gradle file. For example, if you are interested in generating the HTML documentation, then you need to add the following dokkaHtml block:

dokkaHtml {
    moduleName.set("My module's documentation")
}

The above will set the overall title of the documentation for the associated (gradle) module. This is primarily displayed in the documentation’s (HTML or Javadoc) main index.html page. Dokka allows you to provide different configuration options per source set:

dokkaHtml {
    moduleName.set("My module's documentation")

    dokkaSourceSets {
        configureEach {
            displayName.set(it.name)
            suppress.set(false)
        }
    }
}

We can replace the configureEach block with a specific source set name (e.g. main) if we are only interested in modifying the configuration of the specified source set. Multiple source sets can be configured by adding multiple blocks. So for example, if our module has a main and a test source set, we can configure them like so:

dokkaHtml {
    moduleName.set("My module's documentation")

    dokkaSourceSets {
        main {
            displayName.set("main")
            suppress.set(false)
        }
        test {
            displayName.set("test")
            suppress.set(false)
        }
    }
}

The suppress configuration option is used for including or excluding a source set.

A very useful feature of any documentation engine is the addition of links in external and internal code, which can be used by developers to link their documentation internally (e.g. within their project), or externally (e.g. with the language’s or framework’s documentation). In KDoc, this is achieved using Markdown syntax. Any entity that is included in square brackets [] will be resolved as a link. The link may be an entity in the same project, or part of an external documentation.

When dokka is generating the documentation, it will attempt to contact various online sources which will be used for linking to a specific entity (e.g. whether a class can be found in the Oracle JDK, or Kotlin documentation, or even the Android documentation). You can disable this functionality by using the offline mode attribute:

dokkaHtml {
    moduleName.set("My module's documentation")
    offlineMode.set(true)
    dokkaSourceSets {
        main {
            displayName.set("main")
            suppress.set(false)
            includes.from("description.md")
        }
    }
}

Now, only local information will be used when resolving entities. If these entities cannot be found, then a link to them will not get generated.

You include the markdown file with the module and package documentation, by adding the includes directive as follows:

dokkaHtml {
    moduleName.set("My module's documentation")

    dokkaSourceSets {
        main {
            displayName.set("main")
            suppress.set(false)
            includes.from("description.md")
        }
    }
}

The above directive instructs Dokka to search for the description.md file in the directory of the corresponding gradle module, and use the package and module directives to generate the documentation accordingly.

Packaging the documentation

After you’ve generated your documentation (especially your javadoc documentation), you may want to package it in a jar file and upload it to an external artifact repository, to accompany a corresponding dependency that you’ve created. This can be achieved very easily with a simple task:

task javadocJar(type: Jar, dependsOn: dokkaJavadoc) {
    group "publishing"
    description "Generates javadocJar based on Dokka"
    archiveClassifier.set("javadoc")
    from dokkaJavadoc.outputDirectory
}

The above task will take the output of the dokkaJavadoc task and create a jar from it. It depends on the dokkaJavadoc task and will run it if required. Once this task has been run, a file called: GRADLE_MODULE_NAME-javadoc.jar, will be generated in the module’s build/libs folder.

Example configuration and output

You can find example dokka configuration in this repository. The generated project documentation are available in Javadoc and KDoc formats.