Add integration test target with experimental KDoc resolution enabled (#4454)

* Add integration test target with experimental KDoc resolution enabled
* Create a separate annotation/tag for tests with new KDoc resolution
* Forward new KDoc resolution flаg to IT

Co-authored-by: Oleg Yukhnevich <whyoleg@gmail.com>

Author: AbdullinAM

build-logic/src/main/kotlin/dokkabuild.test-integration.gradle.kts

@@ -38,6 +38,11 @@ tasks.withType<Test>().configureEach {
     val useK2 = dokkaBuild.integrationTestUseK2
     systemProperty.inputProperty("org.jetbrains.dokka.experimental.tryK2", useK2)
         .optional(true)
+
+    val enableExperimentalKDocResolution = dokkaBuild.integrationTestEnableExperimentalKDocResolution
+    systemProperty.inputProperty("org.jetbrains.dokka.analysis.enableExperimentalKDocResolution", enableExperimentalKDocResolution)
+        .optional(true)
+
     useJUnitPlatform {
         if (useK2.get()) excludeTags("onlyDescriptors", "onlyDescriptorsMPP")
     }

build-logic/src/main/kotlin/dokkabuild.test-k2.gradle.kts

@@ -47,13 +47,15 @@ testing {
             // JUnit tags for descriptors (K1) and symbols (K2) are defined with annotations in test classes.
             val onlyDescriptorTags = listOf("onlyDescriptors", "onlyDescriptorsMPP")
             val onlySymbolsTags = listOf("onlySymbols")
+            val onlyNewKdocResolutionTags = listOf("onlyNewKDocResolution")
 
             // Create a new target for _only_ running test compatible with descriptor-analysis (K1).
             val testDescriptorsTarget = targets.register("testDescriptors") {
                 testTask.configure {
-                    description = "Runs tests using descriptors-analysis (K1) (excluding tags: ${onlySymbolsTags})"
+                    val excludedTags = onlySymbolsTags + onlyNewKdocResolutionTags
+                    description = "Runs tests using descriptors-analysis (K1) (excluding tags: ${excludedTags})"
                     useJUnitPlatform {
-                        excludeTags.addAll(onlySymbolsTags)
+                        excludeTags.addAll(excludedTags)
                     }
                     // Analysis dependencies from `descriptorsTestImplementation` should precede all other dependencies
                     // in order to use the shadowed stdlib from the analysis dependencies
@@ -64,16 +66,34 @@ testing {
             // Create a new target for _only_ running test compatible with symbols-analysis (K2).
             val testSymbolsTarget = targets.register("testSymbols") {
                 testTask.configure {
-                    description = "Runs tests using symbols-analysis (K2) (excluding tags: ${onlyDescriptorTags})"
+                    val excludedTags = onlyDescriptorTags + onlyNewKdocResolutionTags
+                    description = "Runs tests using symbols-analysis (K2) (excluding tags: ${excludedTags})"
                     useJUnitPlatform {
-                        excludeTags.addAll(onlyDescriptorTags)
+                        excludeTags.addAll(excludedTags)
                     }
                     // Analysis dependencies from `symbolsTestImplementation` should precede all other dependencies
                     // in order  to use the shadowed stdlib from the analysis dependencies
                     classpath = symbolsTestImplementationResolver.incoming.files + classpath
                 }
             }
 
+            // Create a new target for running symbols-analysis tests with enabled experimental KDoc resolution (K2).
+            val testSymbolsWithNewKDocResolutionTarget = targets.register("testSymbolsWithNewKDocResolution") {
+                testTask.configure {
+                    val excludedTags = onlyDescriptorTags
+                    description = "Runs tests using symbols-analysis and experimental KDoc resolution (K2)" +
+                            " (excluding tags: ${excludedTags})"
+                    useJUnitPlatform {
+                        excludeTags.addAll(excludedTags)
+                    }
+                    // Analysis dependencies from `symbolsTestImplementation` should precede all other dependencies
+                    // in order  to use the shadowed stdlib from the analysis dependencies
+                    classpath = symbolsTestImplementationResolver.incoming.files + classpath
+
+                    systemProperty("org.jetbrains.dokka.analysis.enableExperimentalKDocResolution", "true")
+                }
+            }
+
             // Run both K1 and K2, when running :test
             // don't run the task itself, as it's just an aggregate for K1/K2 tests.
             // Ideally, we don't really need this `test` target, but it's not possible to remove it.
@@ -82,6 +102,7 @@ testing {
                     onlyIf { false }
                     dependsOn(testDescriptorsTarget.map { it.testTask })
                     dependsOn(testSymbolsTarget.map { it.testTask })
+                    dependsOn(testSymbolsWithNewKDocResolutionTarget.map { it.testTask })
                 }
             }
         }

build-logic/src/main/kotlin/dokkabuild/DokkaBuildProperties.kt

@@ -8,7 +8,6 @@ import org.gradle.api.file.ProjectLayout
 import org.gradle.api.provider.Provider
 import org.gradle.api.provider.ProviderFactory
 import org.gradle.jvm.toolchain.JavaLanguageVersion
-import org.jetbrains.kotlin.gradle.dsl.KotlinVersion
 import java.io.File
 import javax.inject.Inject
 
@@ -87,6 +86,11 @@ abstract class DokkaBuildProperties @Inject constructor(
     val integrationTestDokkaVersionOverride: Provider<String> =
         dokkaProperty("integration_test.dokkaVersionOverride") { it }
 
+    /** Control whether integration tests should use the `org.jetbrains.dokka.analysis.enableExperimentalKDocResolution` flag. */
+    val integrationTestEnableExperimentalKDocResolution: Provider<Boolean> =
+        dokkaProperty("integration_test.enableExperimentalKDocResolution", String::toBoolean)
+            .orElse(false)
+
     val androidSdkDir: Provider<File> =
         providers
             // first try finding a local.properties file in any parent directory

dokka-integration-tests/gradle/src/main/kotlin/org/jetbrains/dokka/it/gradle/AbstractGradleIntegrationTest.kt

@@ -112,6 +112,7 @@ abstract class AbstractGradleIntegrationTest : AbstractIntegrationTest() {
 
                     // property flag to use K2
                     add("-P${TestEnvironment.TRY_K2}=${TestEnvironment.shouldUseK2()}")
+                    add("-P${TestEnvironment.TRY_EXPERIMENTAL_KDOC_RESOLUTION}=${TestEnvironment.shouldUseExperimentalKDocResolution()}")
 
                     // Decrease Gradle daemon idle timeout to prevent old agents lingering on CI.
                     // A lower timeout means slower tests, which is preferred over OOMs and locked processes.

dokka-integration-tests/gradle/src/main/kotlin/org/jetbrains/dokka/it/gradle/TestEnvironment.kt

@@ -9,6 +9,7 @@ import org.junit.jupiter.api.Tag
 
 object TestEnvironment {
     const val TRY_K2: String = "org.jetbrains.dokka.experimental.tryK2"
+    const val TRY_EXPERIMENTAL_KDOC_RESOLUTION = "org.jetbrains.dokka.analysis.enableExperimentalKDocResolution"
 
     val isExhaustive: Boolean by systemProperty(String::toBoolean)
 
@@ -19,6 +20,11 @@ object TestEnvironment {
      */
     fun shouldUseK2(): Boolean = getBooleanProperty(TRY_K2)
 
+    /**
+     * By default, it is disabled
+     */
+    fun shouldUseExperimentalKDocResolution(): Boolean = getBooleanProperty(TRY_EXPERIMENTAL_KDOC_RESOLUTION)
+
     private fun getBooleanProperty(propertyName: String): Boolean {
         return System.getProperty(propertyName) in setOf("1", "true")
     }

dokka-subprojects/analysis-kotlin-api/src/test/kotlin/org/jetbrains/dokka/analysis/test/TagsAnnotations.kt

@@ -59,3 +59,20 @@ annotation class OnlySymbols(val reason: String = "")
 )
 @Tag("onlyDescriptorsMPP")
 annotation class OnlyDescriptorsMPP(val reason: String = "")
+
+/**
+ * Run a test only for a new KDoc resolution (with K2)
+ *
+ * After we switch to the new KDoc resolution by default, this annotation should be removed
+ */
+@Target(
+    AnnotationTarget.CLASS,
+    AnnotationTarget.FUNCTION,
+    AnnotationTarget.PROPERTY_GETTER,
+    AnnotationTarget.PROPERTY_SETTER
+)
+@Retention(
+    AnnotationRetention.RUNTIME
+)
+@Tag("onlyNewKDocResolution")
+annotation class OnlyNewKDocResolution(val reason: String = "")

dokka-subprojects/plugin-base/src/test/kotlin/content/kdoc/KDocAmbiguityResolutionTest.kt

@@ -27,13 +27,12 @@ import org.jetbrains.dokka.pages.ClasslikePageNode
 import org.jetbrains.dokka.pages.ContentDRILink
 import org.jetbrains.dokka.pages.ContentPage
 import org.jetbrains.dokka.pages.MemberPageNode
-import utils.OnlySymbols
+import utils.OnlyNewKDocResolution
 import utils.findTestType
-import utils.withExperimentalKDocResolution
 import kotlin.test.Test
 import kotlin.test.assertEquals
 
-@OnlySymbols("KEEP #389: New KDoc resolution")
+@OnlyNewKDocResolution("KEEP #389: New KDoc resolution")
 class KDocAmbiguityResolutionTest : BaseAbstractTest() {
     private val testConfiguration = dokkaConfiguration {
         sourceSets {
@@ -46,7 +45,7 @@ class KDocAmbiguityResolutionTest : BaseAbstractTest() {
     }
 
     @Test
-    fun `#3451 ambiguous link to the class`() = withExperimentalKDocResolution {
+    fun `#3451 ambiguous link to the class`() {
         testInline(
             """
             |/src/main/kotlin/test/source.kt
@@ -120,7 +119,7 @@ class KDocAmbiguityResolutionTest : BaseAbstractTest() {
     }
 
     @Test
-    fun `#3451 ambiguous link to function and property`() = withExperimentalKDocResolution {
+    fun `#3451 ambiguous link to function and property`() {
         testInline(
             """
             |/src/main/kotlin/test/source.kt
@@ -212,7 +211,7 @@ class KDocAmbiguityResolutionTest : BaseAbstractTest() {
     }
 
     @Test
-    fun `#3451 ambiguous link with factory functions`() = withExperimentalKDocResolution {
+    fun `#3451 ambiguous link with factory functions`() {
         testInline(
             """
             |/src/main/kotlin/test/source.kt
@@ -359,7 +358,7 @@ class KDocAmbiguityResolutionTest : BaseAbstractTest() {
     }
 
     @Test
-    fun `#3451 ambiguous link to inner class`() = withExperimentalKDocResolution {
+    fun `#3451 ambiguous link to inner class`() {
         testInline(
             """
             |/src/main/kotlin/test/source.kt
@@ -411,7 +410,7 @@ class KDocAmbiguityResolutionTest : BaseAbstractTest() {
     }
 
     @Test
-    fun `#3179 KDoc link to property`() = withExperimentalKDocResolution {
+    fun `#3179 KDoc link to property`() {
         testInline(
             """
             |/src/main/kotlin/test/source.kt
@@ -485,7 +484,7 @@ class KDocAmbiguityResolutionTest : BaseAbstractTest() {
     }
 
     @Test
-    fun `#3179 KDoc link to parameter`() = withExperimentalKDocResolution {
+    fun `#3179 KDoc link to parameter`() {
         testInline(
             """
             |/src/main/kotlin/test/source.kt
@@ -535,7 +534,7 @@ class KDocAmbiguityResolutionTest : BaseAbstractTest() {
 
 
     @Test
-    fun `#3604 KDoc reference to class from constructor`() = withExperimentalKDocResolution {
+    fun `#3604 KDoc reference to class from constructor`() {
         testInline(
             """
             |/src/main/kotlin/test/source.kt
@@ -603,7 +602,7 @@ class KDocAmbiguityResolutionTest : BaseAbstractTest() {
     }
 
     @Test
-    fun `#3632 KDoc reference to extension`() = withExperimentalKDocResolution {
+    fun `#3632 KDoc reference to extension`() {
         testInline(
             """
             |/src/main/kotlin/test/source.kt
@@ -665,7 +664,7 @@ class KDocAmbiguityResolutionTest : BaseAbstractTest() {
     }
 
     @Test
-    fun `#3632 KDoc reference to member in extension`() = withExperimentalKDocResolution {
+    fun `#3632 KDoc reference to member in extension`() {
         testInline(
             """
             |/src/main/kotlin/test/source.kt
@@ -725,7 +724,7 @@ class KDocAmbiguityResolutionTest : BaseAbstractTest() {
     }
 
     @Test
-    fun `#4327 KDoc reference to properties named the same as constructor parameters`() = withExperimentalKDocResolution {
+    fun `#4327 KDoc reference to properties named the same as constructor parameters`() {
         testInline(
             """
             |/src/main/kotlin/test/source.kt

dokka-subprojects/plugin-base/src/test/kotlin/markdown/LinkTest.kt

@@ -16,9 +16,9 @@ import org.jetbrains.dokka.pages.ClasslikePageNode
 import org.jetbrains.dokka.pages.ContentDRILink
 import org.jetbrains.dokka.pages.MemberPageNode
 import utils.OnlyDescriptors
+import utils.OnlyNewKDocResolution
 import utils.OnlySymbols
 import utils.text
-import utils.withExperimentalKDocResolution
 import kotlin.test.Test
 import kotlin.test.assertEquals
 import kotlin.test.assertNotNull
@@ -613,8 +613,8 @@ class LinkTest : BaseAbstractTest() {
     }
 
     @Test
-    @OnlySymbols("KEEP #389: New KDoc resolution")
-    fun `fully qualified link should lead to function`() = withExperimentalKDocResolution {
+    @OnlyNewKDocResolution("KEEP #389: New KDoc resolution")
+    fun `fully qualified link should lead to function`() {
         // for the test case, there is the only one link candidate in K1 and K2
         testInline(
             """
@@ -796,8 +796,8 @@ class LinkTest : BaseAbstractTest() {
     }
 
     @Test
-    @OnlySymbols("KEEP #389: New KDoc resolution")
-    fun `short link should lead to function`() = withExperimentalKDocResolution {
+    @OnlyNewKDocResolution("KEEP #389: New KDoc resolution")
+    fun `short link should lead to function`() {
         testInline(
             """
             |/src/main/kotlin/Testing.kt

dokka-subprojects/plugin-base/src/test/kotlin/utils/TagsAnnotations.kt

@@ -58,3 +58,20 @@ annotation class OnlySymbols(val reason: String = "")
 )
 @Tag("onlyDescriptorsMPP")
 annotation class OnlyDescriptorsMPP(val reason: String = "")
+
+/**
+ * Run a test only for a new KDoc resolution (with K2)
+ *
+ * After we switch to the new KDoc resolution by default, this annotation should be removed
+ */
+@Target(
+    AnnotationTarget.CLASS,
+    AnnotationTarget.FUNCTION,
+    AnnotationTarget.PROPERTY_GETTER,
+    AnnotationTarget.PROPERTY_SETTER
+)
+@Retention(
+    AnnotationRetention.RUNTIME
+)
+@Tag("onlyNewKDocResolution")
+annotation class OnlyNewKDocResolution(val reason: String = "")

dokka-subprojects/plugin-base/src/test/kotlin/utils/systemProperties.kt

@@ -21,13 +21,6 @@ internal fun withSinceKotlin(block: () -> Unit): Unit =
 internal fun withAllowKotlinPackage(block: () -> Unit): Unit =
     DokkaBaseInternalConfiguration.withProperty("org.jetbrains.dokka.analysis.allowKotlinPackage", "true", block)
 
-/**
- * This property works only for K2
- * Enable experimental KDoc resolution
- */
-internal fun withExperimentalKDocResolution(block: () -> Unit): Unit =
-    DokkaBaseInternalConfiguration.withProperty("org.jetbrains.dokka.analysis.enableExperimentalKDocResolution", "true", block)
-
 internal fun DokkaBaseInternalConfiguration.withProperty(propertyName: String, value: String, block: () -> Unit) {
     setProperty(propertyName, value)
     try {