From d744e49b1bf9fdcd25c4021492fa450c388cba22 Mon Sep 17 00:00:00 2001 From: Oleg Yukhnevich Date: Mon, 20 Nov 2023 14:35:26 +0200 Subject: [PATCH] Take the minimum SinceKotlin version if they differ for AllTypesPage --- .../annotations/SinceKotlinTransformer.kt | 32 ++++--- .../tags/SinceKotlinTagContentProvider.kt | 6 +- .../documentables/DefaultPageCreator.kt | 13 ++- .../test/kotlin/content/AllTypesPageTest.kt | 84 +++++++++++++++++++ .../src/test/kotlin/utils/systemProperties.kt | 4 + 5 files changed, 122 insertions(+), 17 deletions(-) diff --git a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/annotations/SinceKotlinTransformer.kt b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/annotations/SinceKotlinTransformer.kt index 3ec79b4a79..b99d16e13b 100644 --- a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/annotations/SinceKotlinTransformer.kt +++ b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/annotations/SinceKotlinTransformer.kt @@ -37,20 +37,29 @@ public class SinceKotlinVersion(str: String) : Comparable { } 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.transform(parent: SourceSetDependent? = 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/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/tags/SinceKotlinTagContentProvider.kt b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/tags/SinceKotlinTagContentProvider.kt index 7c35f71910..0299fd9b63 100644 --- a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/tags/SinceKotlinTagContentProvider.kt +++ b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/transformers/pages/tags/SinceKotlinTagContentProvider.kt @@ -5,6 +5,7 @@ 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 @@ -12,9 +13,8 @@ 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/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/translators/documentables/DefaultPageCreator.kt b/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/translators/documentables/DefaultPageCreator.kt index a5f702857f..6f3ecf13fc 100644 --- a/dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/translators/documentables/DefaultPageCreator.kt +++ b/dokka-subprojects/plugin-base/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, List>> @@ -312,10 +313,16 @@ 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 @@ -323,7 +330,7 @@ public open class DefaultPageCreator( 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 index 217b53bc6e..4670dfa77e 100644 --- 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 index 7b98d802e5..4f15c5665b 100644 --- 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 {