Overcome issue with fastutil (#3409)

dokka-integration-tests/gradle/projects/it-basic/src/main/kotlin/RootPackageClass.kt

@@ -2,6 +2,8 @@
 
 /**
  * A class that lives inside the root package
+ *
+ * <me@mail.com>
  */
 class RootPackageClass {
     val description = "I do live in the root package!"

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") {
+                +"""
+                    /**
+                     * <me@mail.com>
+                     */
+                    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(),
+        )
+    }
+}

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/**") }

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/**") }
+

gradle/libs.versions.toml

@@ -29,6 +29,11 @@ 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
 jackson = "2.12.7" # jackson 2.13.X does not support kotlin language version 1.4, check before updating
@@ -112,6 +117,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" }