How do I document a Kotlin package like with the Java `package-info.java` in an IntelliJ IDEA/Gradle project?

Question

kotlinlang.org says that a separate markdown file documents all packages. Is there a canonical path for that markdown file in an IntelliJ IDEA project? Is there a canonical way to process that file with Gradle? Is there a way to have these .md files alongside .kt files in the package directory?

Answer 1

If you want to produce your documentations using Dokka, you can create a single markdown (.md) file with headers for each package (or probably separate markdown file in each package with a single header in that file for that package):

my-packages-docs.md:

# Package com.example.mylibrary.firstpackage

This is the docs for firstpackage.

# Package com.example.mylibrary.anotherpackage

This is the docs for anotherpackage.

## This is a subheader for anotherpackages docs

Include the markdown file in the Dokka result docs by passing the path of the file(s) to Dokka using the -include command line parameter or the corresponding parameters in Ant, Maven and Gradle plugins.

Here is an example configuration for Dokka in my library build.gradle.kts file (Kotlin DSL):

tasks.dokkaHtml.configure {
    dokkaSourceSets {
        configureEach { // OR named("main") {
            includes.from("my-packages-docs.md", "another.md")
            ...
        }
    }
}

Refer to Kotlin documentations for more information.