Take the minimum SinceKotlin version if they differ for AllTypesPage

Kotlin · Nov 20, 2023 · d744e49 · d744e49
1 parent bd114f0
commit d744e49
Show file tree

Hide file tree

Showing 5 changed files with 122 additions and 17 deletions.
diff --git a/.../kotlin/org/jetbrains/dokka/base/transformers/pages/annotations/SinceKotlinTransformer.kt b/.../kotlin/org/jetbrains/dokka/base/transformers/pages/annotations/SinceKotlinTransformer.kt
@@ -37,20 +37,29 @@ public class SinceKotlinVersion(str: String) : Comparable<SinceKotlinVersion> {
     }
 
     override fun toString(): String = parts.joinToString(".")
+
+    internal companion object {
+        internal const val SINCE_KOTLIN_TAG_NAME = "Since Kotlin"
+
+        private val minSinceKotlinVersionOfPlatform = mapOf(
+            Platform.common to SinceKotlinVersion("1.0"),
+            Platform.jvm to SinceKotlinVersion("1.0"),
+            Platform.js to SinceKotlinVersion("1.1"),
+            Platform.native to SinceKotlinVersion("1.3"),
+            Platform.wasm to SinceKotlinVersion("1.8"),
+        )
+
+        fun minSinceKotlinVersionOfPlatform(platform: Platform): SinceKotlinVersion {
+            return minSinceKotlinVersionOfPlatform[platform]
+                ?: throw IllegalStateException("No value for platform: $platform")
+        }
+    }
 }
 
 public class SinceKotlinTransformer(
     public val context: DokkaContext
 ) : DocumentableTransformer {
 
-    private val minSinceKotlinVersionOfPlatform = mapOf(
-        Platform.common to SinceKotlinVersion("1.0"),
-        Platform.jvm to SinceKotlinVersion("1.0"),
-        Platform.js to SinceKotlinVersion("1.1"),
-        Platform.native to SinceKotlinVersion("1.3"),
-        Platform.wasm to SinceKotlinVersion("1.8"),
-    )
-
     override fun invoke(original: DModule, context: DokkaContext): DModule = original.transform() as DModule
 
     private fun <T : Documentable> T.transform(parent: SourceSetDependent<SinceKotlinVersion>? = null): Documentable {
@@ -132,8 +141,7 @@ public class SinceKotlinTransformer(
                 ?.params?.let { it["version"] as? StringValue }?.value
                 ?.let { SinceKotlinVersion(it) }
 
-        val minSinceKotlin = minSinceKotlinVersionOfPlatform[sourceSet.analysisPlatform]
-            ?: throw IllegalStateException("No value for platform: ${sourceSet.analysisPlatform}")
+        val minSinceKotlin = SinceKotlinVersion.minSinceKotlinVersionOfPlatform(sourceSet.analysisPlatform)
 
         return annotatedVersion?.takeIf { version -> version >= minSinceKotlin } ?: minSinceKotlin
     }
@@ -155,6 +163,8 @@ public class SinceKotlinTransformer(
 
             val version = versions[sourceSet]
 
+            // the structure of custom tag content for SinceKotlin should be in sync
+            // with how DefaultPageCreator.contentForAllTypes reads it
             val sinceKotlinCustomTag = CustomTagWrapper(
                 CustomDocTag(
                     listOf(
@@ -164,7 +174,7 @@ public class SinceKotlinTransformer(
                     ),
                     name = MARKDOWN_ELEMENT_FILE_NAME
                 ),
-                "Since Kotlin"
+                SinceKotlinVersion.SINCE_KOTLIN_TAG_NAME
             )
             if (acc[sourceSet] == null)
                 acc + (sourceSet to DocumentationNode(listOf(sinceKotlinCustomTag)))

diff --git a/.../kotlin/org/jetbrains/dokka/base/transformers/pages/tags/SinceKotlinTagContentProvider.kt b/.../kotlin/org/jetbrains/dokka/base/transformers/pages/tags/SinceKotlinTagContentProvider.kt
@@ -5,16 +5,16 @@
 package org.jetbrains.dokka.base.transformers.pages.tags
 
 import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.base.transformers.pages.annotations.SinceKotlinVersion
 import org.jetbrains.dokka.base.translators.documentables.KDOC_TAG_HEADER_LEVEL
 import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder.DocumentableContentBuilder
 import org.jetbrains.dokka.model.doc.CustomTagWrapper
 import org.jetbrains.dokka.pages.TextStyle
 
 public object SinceKotlinTagContentProvider : CustomTagContentProvider {
 
-    private const val SINCE_KOTLIN_TAG_NAME = "Since Kotlin"
-
-    override fun isApplicable(customTag: CustomTagWrapper): Boolean = customTag.name == SINCE_KOTLIN_TAG_NAME
+    override fun isApplicable(customTag: CustomTagWrapper): Boolean =
+        customTag.name == SinceKotlinVersion.SINCE_KOTLIN_TAG_NAME
 
     override fun DocumentableContentBuilder.contentForDescription(
         sourceSet: DokkaConfiguration.DokkaSourceSet,

diff --git a/.../src/main/kotlin/org/jetbrains/dokka/base/translators/documentables/DefaultPageCreator.kt b/.../src/main/kotlin/org/jetbrains/dokka/base/translators/documentables/DefaultPageCreator.kt
@@ -27,6 +27,7 @@ import org.jetbrains.dokka.analysis.kotlin.internal.DocumentableSourceLanguagePa
 import org.jetbrains.dokka.analysis.kotlin.internal.DocumentableLanguage
 import org.jetbrains.dokka.base.DokkaBaseInternalConfiguration
 import org.jetbrains.dokka.base.pages.AllTypesPageNode
+import org.jetbrains.dokka.base.transformers.pages.annotations.SinceKotlinVersion
 import kotlin.reflect.KClass
 
 internal typealias GroupedTags = Map<KClass<out TagWrapper>, List<Pair<DokkaSourceSet?, TagWrapper>>>
@@ -312,18 +313,24 @@ public open class DefaultPageCreator(
                 typelike.descriptions[sourceSet]?.let { sourceSet to it }
             }.selectBestVariant { firstParagraphBrief(it.root) }
 
-            val customTags = typelike.customTags.values.mapNotNull { sourceSetTag ->
+            val sinceKotlinTag = typelike.customTags[SinceKotlinVersion.SINCE_KOTLIN_TAG_NAME]?.let { sourceSetTag ->
                 typelike.sourceSets.mapNotNull { sourceSet ->
                     sourceSetTag[sourceSet]?.let { sourceSet to it }
-                }.selectBestVariant { it }
+                }.minByOrNull { (sourceSet, tagWrapper) ->
+                    // this code should be in sync with how SinceKotlinTransformer.appendSinceKotlin works
+                    val customTag = tagWrapper.root as? CustomDocTag
+                    val sinceKotlinVersionText = customTag?.children?.firstOrNull() as? Text
+                    sinceKotlinVersionText?.body?.let(::SinceKotlinVersion)
+                        ?: SinceKotlinVersion.minSinceKotlinVersionOfPlatform(sourceSet.analysisPlatform)
+                }
             }
 
             // qualified name will never be 'null' for classlike and typealias
             link(typelike.qualifiedName()!!, typelike.dri)
             comment?.let { (sourceSet, description) ->
                 createBriefComment(typelike, sourceSet, description)
             }
-            customTags.forEach { (sourceSet, tag) ->
+            sinceKotlinTag?.let { (sourceSet, tag) ->
                 createBriefCustomTags(sourceSet, tag)
             }
         }

diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/content/AllTypesPageTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/content/AllTypesPageTest.kt
@@ -9,6 +9,7 @@ import org.jetbrains.dokka.base.pages.AllTypesPageNode
 import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
 import org.jetbrains.dokka.pages.RootPageNode
 import utils.withAllTypesPage
+import utils.withSinceKotlin
 import kotlin.test.Test
 import kotlin.test.assertNotNull
 import kotlin.test.assertNull
@@ -339,4 +340,87 @@ class AllTypesPageTest : BaseAbstractTest() {
                 }
             }
         }
+
+
+    @Test
+    fun `since kotlin is the same for all sourceSets`() = withAllTypesPage {
+        withSinceKotlin {
+            testInline(
+                """
+                |/src/common/test.kt
+                |package test
+                |@SinceKotlin("1.3")
+                |expect class ExpectActual
+                |/src/jvm/test.kt
+                |package test
+                |@SinceKotlin("1.3")
+                |actual class ExpectActual
+                |/src/native/test.kt
+                |package test
+                |@SinceKotlin("1.3")
+                |actual class ExpectActual
+                """.trimIndent(),
+                multiplatformConfiguration
+            ) {
+                pagesTransformationStage = { rootPage ->
+                    assertNotNull(rootPage.allTypesPageNode()).content.assertNode {
+                        group {
+                            header { +"root" }
+                        }
+                        header { +"All Types" }
+                        table {
+                            group {
+                                link { +"test.ExpectActual" }
+                                group {
+                                    +"Since Kotlin "
+                                    group { +"1.3" }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    @Test
+    fun `minimal since kotlin is used if it's different between sourceSets`() = withAllTypesPage {
+        withSinceKotlin {
+            testInline(
+                """
+                |/src/common/test.kt
+                |package test
+                |@SinceKotlin("1.4")
+                |expect class ExpectActual
+                |/src/jvm/test.kt
+                |package test
+                |@SinceKotlin("1.2")
+                |actual class ExpectActual
+                |/src/native/test.kt
+                |package test
+                |@SinceKotlin("1.5")
+                |actual class ExpectActual
+                """.trimIndent(),
+                multiplatformConfiguration
+            ) {
+                pagesTransformationStage = { rootPage ->
+                    assertNotNull(rootPage.allTypesPageNode()).content.assertNode {
+                        group {
+                            header { +"root" }
+                        }
+                        header { +"All Types" }
+                        table {
+                            group {
+                                link { +"test.ExpectActual" }
+                                group {
+                                    +"Since Kotlin "
+                                    group { +"1.2" }
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
 }
diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/utils/systemProperties.kt b/dokka-subprojects/plugin-base/src/test/kotlin/utils/systemProperties.kt
@@ -6,10 +6,14 @@ package utils
 
 import org.jetbrains.dokka.base.DokkaBaseInternalConfiguration
 import org.jetbrains.dokka.base.DokkaBaseInternalConfiguration.SHOULD_DISPLAY_ALL_TYPES_PAGE_SYS_PROP
+import org.jetbrains.dokka.base.DokkaBaseInternalConfiguration.SHOULD_DISPLAY_SINCE_KOTLIN_SYS_PROP
 
 internal fun withAllTypesPage(block: () -> Unit): Unit =
     DokkaBaseInternalConfiguration.withProperty(SHOULD_DISPLAY_ALL_TYPES_PAGE_SYS_PROP, "true", block)
 
+internal fun withSinceKotlin(block: () -> Unit): Unit =
+    DokkaBaseInternalConfiguration.withProperty(SHOULD_DISPLAY_SINCE_KOTLIN_SYS_PROP, "true", block)
+
 internal fun DokkaBaseInternalConfiguration.withProperty(propertyName: String, value: String, block: () -> Unit) {
     setProperty(propertyName, value)
     try {