How to configure Dokka for kotlin-multiplatform

Support
1

I’m attempting to generate docca output for my multiplatform library.
I’m using ‘kotlin-multiplatform’ version ‘1.3.0-rc-146’
and org.jetbrains.dokka:dokka-gradle-plugin:0.9.17
and IDEA 2018.2.4

I have common, jvm and js platforms configured.

Docca is stalling with
Could not find method classpath() for arguments [org.jetbrains.dokka:dokka-gradle-plugin:0.9.17]

My build.gradle docca-related entries are:

dependencies {
classpath “org.jetbrains.dokka:dokka-gradle-plugin:0.9.17”
}

apply plugin: ‘org.jetbrains.dokka’

dokka {
outputFormat = ‘html’
outputDirectory = “$buildDir/doc”
}

I can’t work out how to tell docca where to find the (6 sets of) sources in this multiplatform configuration.
The multiplatform documentation I can find at
https://kotlinlang.org/docs/reference/building-mpp-with-gradle.html#setting-up-a-multiplatform-project
seems not(yet) to address this.

2

Dokka does not yet really work with new MPP but I figured out a solution that works for me:

dokka {
    impliedPlatforms = ["Common"] // This will force platform tags for all non-common sources e.g. "JVM"
    kotlinTasks {
        // dokka fails to retrieve sources from MPP-tasks so they must be set empty to avoid exception
        // use sourceRoot instead (see below)
        []
    }
    sourceRoot {
        // assuming there is only a single source dir...
        path = kotlin.sourceSets.commonMain.kotlin.srcDirs[0]
        platforms = ["Common"]
    }
    sourceRoot {
        // assuming there is only a single source dir...
        path = kotlin.sourceSets.jvmMain.kotlin.srcDirs[0]
        platforms = ["JVM"]
    }
}

Good luck!

3

Thanks - this works.
(I actually generate a single doc for the three source sets [common + jvm + js]. Fortunately I use package names which indicate which is which when viewing the documentation).

I’d really like to generate three different sets of documentation (common, common+js and common +jvm) for use when designing MPPs using this library, but I can’t work out how to have the docca plugin invoked three times (with three different configurations).

Suggestions welcome!

4

You can create multiple Dokka tasks by using:

task dokkaSome(type: org.jetbrains.dokka.gradle.DokkaTask) {
    outputFormat = ...
    /* other options */
}
5

Ah! Just what I need. Thanks.

6

Solved: Documentation for MPP
Here’s what worked for me, based on the valuable inputs from knolle and Simon.Ogorodnik (above)…


// Do not apply the docca plugin

task docCommon(type: org.jetbrains.dokka.gradle.DokkaTask) {

outputFormat = 'javadoc'

outputDirectory = "$buildDir/doc_common"

impliedPlatforms = ["Common"] // This will force platform tags for all non-common sources e.g. "JVM"

kotlinTasks {

// dokka fails to retrieve sources from MPP-tasks so they must be set empty to avoid exception

// use sourceRoot instead (see below)

[]

}

includes = ['packages.md', 'extra.md']

sourceRoot {

// assuming there is only a single source dir...

path = kotlin.sourceSets.commonMain.kotlin.srcDirs[0]

platforms = ["Common"]

}

}//------------

task docJs(type: org.jetbrains.dokka.gradle.DokkaTask) {

outputFormat = 'javadoc'

outputDirectory = "$buildDir/doc_js"

impliedPlatforms = ["Common"] // This will force platform tags for all non-common sources e.g. "JVM"

kotlinTasks {

// dokka fails to retrieve sources from MPP-tasks so they must be set empty to avoid exception

// use sourceRoot instead (see below)

[]

}

includes = ['packages.md', 'extra.md']

sourceRoot {

// assuming there is only a single source dir...

path = kotlin.sourceSets.commonMain.kotlin.srcDirs[0]

platforms = ["Common"]

}

sourceRoot {

// assuming there is only a single source dir...

path = kotlin.sourceSets.jsMain.kotlin.srcDirs[0]

platforms = ["JS"]

}

}//--------------

task docJvm(type: org.jetbrains.dokka.gradle.DokkaTask) {

outputFormat = 'javadoc'

outputDirectory = "$buildDir/doc_jvm"

impliedPlatforms = ["Common"] // This will force platform tags for all non-common sources e.g. "JVM"

kotlinTasks {

// dokka fails to retrieve sources from MPP-tasks so they must be set empty to avoid exception

// use sourceRoot instead (see below)

[]

}

includes = ['packages.md', 'extra.md']

sourceRoot {

// assuming there is only a single source dir...

path = kotlin.sourceSets.commonMain.kotlin.srcDirs[0]

platforms = ["Common"]

}

sourceRoot {

// assuming there is only a single source dir...

path = kotlin.sourceSets.jvmMain.kotlin.srcDirs[0]

platforms = ["JVM"]

}

}//--------------

// Invoke this task to generate all three sets of documentation

task doc{

dependsOn docCommon

dependsOn docJvm

dependsOn docJs

}//----------
7

Do you expose any external types in your api? Im using this solution but the output contains <ERROR CLASS> for the coroutines types I expose.

The stdlib types resolve just fine.

Adding

externalDocumentationLink {
    url = new URL("https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/")
}

didn’t help as I read <ERROR CLASS> is caused by class path issues

8

No, I don’t. Can’t help. Sorry.

9

I use the externalDocumentationLink like you posted and it works for me. However, I’m referring to "https://docs.gradle.org/4.10.2/javadoc/". Your problem may be coroutine specific.

10

My previous example has a problem: by making kotlinTasks completely empty, the Dokka generation classpath is missing dependencies.
Using Dokka 0.9.18 you should see this message for such unresolved links:
Unresolved link to ExternalClass in doc comment of my.package.MyClass

To fix this, I did the following (assuming you have “jvm” as a target for your MPP):

    kotlinTasks {
        // dokka fails to retrieve sources from MPP-tasks so we only define the jvm task
        [project.compileKotlinJvm]
    }
    sourceRoot {
        // assuming only single source dir
        path = project.kotlin.sourceSets.commonMain.kotlin.srcDirs[0]
        platforms = ["Common"]
    }
    // although the JVM sources are now taken from the task,
    // we still define the jvm source root to get the JVM marker in the generated html
    sourceRoot {
        // assuming only single source dir
        path = project.kotlin.sourceSets.jvmMain.kotlin.srcDirs[0]
        platforms = ["JVM"]
    }