From 69899624cc1d9fb843699ad41f7b669f5723dc85 Mon Sep 17 00:00:00 2001 From: Oleg Yukhnevich Date: Tue, 12 Dec 2023 20:26:01 +0200 Subject: [PATCH 1/2] Overcome fastutil issue --- .../src/main/kotlin/RootPackageClass.kt | 2 + .../test/documentable/SpecialCharacterTest.kt | 49 +++++++++++++++++++ .../build.gradle.kts | 22 +++++++++ .../analysis-kotlin-symbols/build.gradle.kts | 24 +++++++++ gradle/libs.versions.toml | 2 + 5 files changed, 99 insertions(+) create mode 100644 dokka-subprojects/analysis-kotlin-api/src/test/kotlin/org/jetbrains/dokka/analysis/test/documentable/SpecialCharacterTest.kt diff --git a/dokka-integration-tests/gradle/projects/it-basic/src/main/kotlin/RootPackageClass.kt b/dokka-integration-tests/gradle/projects/it-basic/src/main/kotlin/RootPackageClass.kt index 8ff6c750ad..0cc5b487c0 100644 --- a/dokka-integration-tests/gradle/projects/it-basic/src/main/kotlin/RootPackageClass.kt +++ b/dokka-integration-tests/gradle/projects/it-basic/src/main/kotlin/RootPackageClass.kt @@ -2,6 +2,8 @@ /** * A class that lives inside the root package + * + * */ class RootPackageClass { val description = "I do live in the root package!" diff --git a/dokka-subprojects/analysis-kotlin-api/src/test/kotlin/org/jetbrains/dokka/analysis/test/documentable/SpecialCharacterTest.kt b/dokka-subprojects/analysis-kotlin-api/src/test/kotlin/org/jetbrains/dokka/analysis/test/documentable/SpecialCharacterTest.kt new file mode 100644 index 0000000000..302076d185 --- /dev/null +++ b/dokka-subprojects/analysis-kotlin-api/src/test/kotlin/org/jetbrains/dokka/analysis/test/documentable/SpecialCharacterTest.kt @@ -0,0 +1,49 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package org.jetbrains.dokka.analysis.test.documentable + +import org.jetbrains.dokka.analysis.test.api.kotlinJvmTestProject +import org.jetbrains.dokka.analysis.test.api.parse +import org.jetbrains.dokka.model.doc.* +import kotlin.test.Test +import kotlin.test.assertEquals + +class SpecialCharacterTest { + + @Test + fun `should be able to parse email`() { + val project = kotlinJvmTestProject { + ktFile("Klass.kt") { + +""" + /** + * + */ + class Klass + """ + } + } + + val module = project.parse() + + val pkg = module.packages.single() + val cls = pkg.classlikes.single() + + assertEquals("Klass", cls.name) + + val text = P( + listOf( + Text("<", params = mapOf("content-type" to "html")), + Text("me@mail.com"), + Text(">", params = mapOf("content-type" to "html")) + ) + ) + val description = Description(CustomDocTag(listOf(text), name = "MARKDOWN_FILE")) + + assertEquals( + DocumentationNode(listOf(description)), + cls.documentation.values.single(), + ) + } +} diff --git a/dokka-subprojects/analysis-kotlin-descriptors/build.gradle.kts b/dokka-subprojects/analysis-kotlin-descriptors/build.gradle.kts index 8d076bf5de..d698511dde 100644 --- a/dokka-subprojects/analysis-kotlin-descriptors/build.gradle.kts +++ b/dokka-subprojects/analysis-kotlin-descriptors/build.gradle.kts @@ -27,3 +27,25 @@ tasks.shadowJar { // from the dependencies are loaded, and not just a single one. mergeServiceFiles() } + +/** + * hack for shadow jar and fastutil because of kotlin-compiler + * + * KT issue: https://youtrack.jetbrains.com/issue/KT-47150 + * + * what is happening here? + * fastutil is removed from shadow-jar completely, + * instead we declare a maven RUNTIME dependency on fastutil; + * this dependency will be fetched by Gradle at build time (as any other dependency from maven-central) + * + * why do we need this? + * because `kotlin-compiler` artifact includes unshaded (not-relocated) STRIPPED `fastutil` dependency, + * STRIPPED here means, that it doesn't provide full `fastutil` classpath, but only a part of it which is used + * and so when shadowJar task is executed it takes classes from `fastutil` from `kotlin-compiler` and adds it to shadow-jar + * then adds all other classes from `fastutil` coming from `markdown-jb`, + * but because `fastutil` from `kotlin-compiler` is STRIPPED, some classes (like `IntStack`) has no some methods + * and so such classes are not replaced afterward by `shadowJar` task - it visits every class once + * + */ +dependencies.shadow(libs.fastutil) +tasks.shadowJar { exclude("it/unimi/dsi/fastutil/**") } diff --git a/dokka-subprojects/analysis-kotlin-symbols/build.gradle.kts b/dokka-subprojects/analysis-kotlin-symbols/build.gradle.kts index 87635df1c6..90e6afd99d 100644 --- a/dokka-subprojects/analysis-kotlin-symbols/build.gradle.kts +++ b/dokka-subprojects/analysis-kotlin-symbols/build.gradle.kts @@ -89,3 +89,27 @@ tasks.shadowJar { // from the dependencies are loaded, and not just a single one. mergeServiceFiles() } + + +/** + * hack for shadow jar and fastutil because of kotlin-compiler + * + * KT issue: https://youtrack.jetbrains.com/issue/KT-47150 + * + * what is happening here? + * fastutil is removed from shadow-jar completely, + * instead we declare a maven RUNTIME dependency on fastutil; + * this dependency will be fetched by Gradle at build time (as any other dependency from maven-central) + * + * why do we need this? + * because `kotlin-compiler` artifact includes unshaded (not-relocated) STRIPPED `fastutil` dependency, + * STRIPPED here means, that it doesn't provide full `fastutil` classpath, but only a part of it which is used + * and so when shadowJar task is executed it takes classes from `fastutil` from `kotlin-compiler` and adds it to shadow-jar + * then adds all other classes from `fastutil` coming from `markdown-jb`, + * but because `fastutil` from `kotlin-compiler` is STRIPPED, some classes (like `IntStack`) has no some methods + * and so such classes are not replaced afterward by `shadowJar` task - it visits every class once + * + */ +dependencies.shadow(libs.fastutil) +tasks.shadowJar { exclude("it/unimi/dsi/fastutil/**") } + diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 6f8ff57166..448747a637 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -29,6 +29,7 @@ kotlinx-html = "0.9.1" ## Markdown jetbrains-markdown = "0.5.2" +fastutil = "8.5.12" ## JSON jackson = "2.12.7" # jackson 2.13.X does not support kotlin language version 1.4, check before updating @@ -112,6 +113,7 @@ korlibs-template = { module = "com.soywiz.korlibs.korte:korte-jvm", version.ref #### Markdown #### jetbrains-markdown = { module = "org.jetbrains:markdown", version.ref = "jetbrains-markdown" } +fastutil = { module = "it.unimi.dsi:fastutil", version.ref = "fastutil" } #### Jackson #### jackson-kotlin = { module = "com.fasterxml.jackson.module:jackson-module-kotlin", version.ref = "jackson" } From 56cf3aa76e09b4156262e2debed8335e0bea0758 Mon Sep 17 00:00:00 2001 From: Oleg Yukhnevich Date: Tue, 19 Dec 2023 16:36:38 +0200 Subject: [PATCH 2/2] Add comment regarding the used fastutil version --- gradle/libs.versions.toml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/gradle/libs.versions.toml b/gradle/libs.versions.toml index 448747a637..18fc27e898 100644 --- a/gradle/libs.versions.toml +++ b/gradle/libs.versions.toml @@ -29,6 +29,10 @@ kotlinx-html = "0.9.1" ## Markdown jetbrains-markdown = "0.5.2" +# This version SHOULD be compatible with both used in `koltin-compiler` and in `jetbrains-markdown` +# version used in `kotlin-compiler` is located in https://github.com/JetBrains/kotlin/blob/c9ad09f4dcaae7792cdf27fbdc8c718443d0ad51/gradle/versions.properties#L14 +# verison used in `jetbrains-markdown` is located in https://github.com/JetBrains/markdown/blob/0f10d90f8f75a6c261e6f5a4f23d29c6cf088a92/build.gradle.kts#L92 +# In most cases using the latest version should work (be careful during MAJOR or MINOR version changes) fastutil = "8.5.12" ## JSON