Multi-module project fails to resolve inter-module links

[ianbotsf]

Describe the bug
While attempting to use Dokka with a multi-module project (smithy-kotlin), it is observed that code in a dependent module which references types in a dependency module leads to generated documentation containing Error class: unknown class.

Expected behaviour
It is expected that types declared in dependency modules resolve correctly in docs for dependent modules.

Screenshots
(coming soon)

To Reproduce

• Clone smithy-kotlin
• Run ./gradlew -Dorg.gradle.jvmargs='-Xmx6G -XX:MaxMetaspaceSize=2G' dokkaHtmlMultiModule
  • Note that Dokka will hang if insufficient memory is available, hence the -Xmx6G -XX:MaxMetaspaceSize=2G arguments
• Observe that no errors/warnings are reported and Gradle exits successfully
• Open an HTML doc page for a class in a dependent module which uses types from a dependency module
  • For example: build/dokka/htmlMultiModule/runtime/runtime-core/aws.smithy.kotlin.runtime.client/index.html
• Observe Error class: unknown class errors wherever dependency types are referenced

Dokka configuration
The Dokka configuration is part of the root build.gradle.kts file:

allprojects {
    // ...

    tasks.withType<org.jetbrains.dokka.gradle.AbstractDokkaTask>().configureEach {
        val sdkVersion: String by project
        moduleVersion.set(sdkVersion)

        val year = java.time.LocalDate.now().year
        val pluginConfigMap = mapOf(
            "org.jetbrains.dokka.base.DokkaBase" to """
                {
                    "customStyleSheets": [
                        "${rootProject.file("docs/dokka-presets/css/logo-styles.css")}",
                        "${rootProject.file("docs/dokka-presets/css/aws-styles.css")}"
                    ],
                    "customAssets": [
                        "${rootProject.file("docs/dokka-presets/assets/logo-icon.svg")}",
                        "${rootProject.file("docs/dokka-presets/assets/aws_logo_white_59x35.png")}"
                    ],
                    "footerMessage": "© $year, Amazon Web Services, Inc. or its affiliates. All rights reserved.",
                    "separateInheritedMembers" : true
                }
            """
        )
        pluginsMapConfiguration.set(pluginConfigMap)
    }
}

// ...

tasks.dokkaHtmlMultiModule.configure {
    moduleName.set("Smithy Kotlin")

    includes.from(
        rootProject.file("docs/dokka-presets/README.md"),
    )

    val excludeFromDocumentation = listOf(
        project(":runtime:testing"),
        project(":runtime:smithy-test"),
    )
    removeChildTasks(excludeFromDocumentation)
}

Installation

• Operating system: Amazon Linux 2
• Build tool: Gradle v7.4.2
• Dokka version: 1.7.10 (reproduced on a recent commit from master as well)

Additional context
(n/a)

Are you willing to provide a PR?
I don't understand the root cause. Otherwise, I'd be happy to submit a PR.

[IgnatBeresnev]

The problem might be related to Kotlin not having proper support for multiplatform projects with a single target, KT-52664.

Setting kotlin.mpp.enableCompatibilityMetadataVariant=true helps, but it might not for 1.7.20.

This problem was also discussed in Kotlin Slack: https://kotlinlang.slack.com/archives/C0F4UNJET/p1664570734894159

[ianbotsf]

Yes and to follow up: setting kotlin.mpp.enableCompatibilityMetadataVariant=true has resulted in successful resolution of inter-module links but we are blocked on upgrading to 1.7.20 (and beyond, presumably) until this is fixed.

[ianbotsf]

Any update on this issue? We're still pinned to Kotlin 1.7.10 until this is fixed. We've tried regressing on 1.7.20 and 1.8.0 and both versions cause the Error class: unknown class to reappear.

[IgnatBeresnev]

(to comment on the previous post: we continued the discussion in Kotlin Community Slack, and found a workaround)

JFYI There were some changes in Kotlin 1.9.0-Beta that might affect this issue or the workaround, but it's unclear as of now whether these changes will be shipped in the final release version.

Do ping us if it starts blocking you again though, please

[IgnatBeresnev]

This particular problem was more difficult to resolve as fixing it for aws projects broke some other projects like ktor.

However, we seem to have found a workaround, and it will be released in Dokka 1.9.0, which should hopefully happen next week. I've provided more information about it in #3122.

Let's keep this issue open until you migrate and verify that you are able to build documentation without this problem.

[lauzadis]

Hi Ignat, thanks for the update. I just tried upgrading our Kotlin/Dokka versions to 1.9.0 and built some test docs, but still see <Error class: unknown class>.