[KPM] Mark overwriting custom capabilities as advanced

libraries/tools/kotlin-gradle-plugin/build.gradle.kts

@@ -28,6 +28,8 @@ pill {
 
 kotlin.sourceSets.all {
     languageSettings.optIn("kotlin.RequiresOptIn")
+    languageSettings.optIn("org.jetbrains.kotlin.gradle.plugin.mpp.external.ExternalVariantApi")
+    languageSettings.optIn("org.jetbrains.kotlin.gradle.plugin.mpp.external.AdvancedExternalVariantApi")
 }
 
 dependencies {

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalVariantApi.kt

@@ -8,10 +8,14 @@ package org.jetbrains.kotlin.gradle.plugin.mpp.external
 import org.gradle.api.Project
 import org.jetbrains.kotlin.gradle.dsl.KotlinTopLevelExtension
 import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.*
+import kotlin.annotation.AnnotationTarget.*
 
 @RequiresOptIn("API is intended to build external Kotlin Targets.")
 annotation class ExternalVariantApi
 
+@RequiresOptIn("API is intended to build external Kotlin Targets *and* is marked as advanced. Consultation with the Kotlin Team advised.")
+annotation class AdvancedExternalVariantApi
+
 @ExternalVariantApi
 val KotlinTopLevelExtension.project: Project
     get() = this.project
@@ -27,4 +31,5 @@ fun KotlinGradleModule.createExternalJvmVariant(
 }
 
 @ExternalVariantApi
-val KotlinGradleVariantInternal.compilationData get() = this.compilationData
+val KotlinGradleVariantInternal.compilationData
+    get() = this.compilationData

libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/pm20/KotlinGradleFragmentConfigurationDefinition.kt

@@ -7,6 +7,7 @@ package org.jetbrains.kotlin.gradle.plugin.mpp.pm20
 
 import org.gradle.api.Project
 import org.gradle.api.artifacts.Configuration
+import org.jetbrains.kotlin.gradle.plugin.mpp.external.AdvancedExternalVariantApi
 import org.jetbrains.kotlin.gradle.plugin.mpp.pm20.util.KotlinNameDisambiguation
 
 /* Internal abbreviation */
@@ -15,9 +16,10 @@ internal typealias ConfigurationDefinition<T> = KotlinGradleFragmentConfiguratio
 data class KotlinGradleFragmentConfigurationDefinition<in T : KotlinGradleFragment>(
     val provider: KotlinGradleFragmentConfigurationProvider,
     val attributes: KotlinGradleFragmentConfigurationAttributes<T> = KotlinGradleFragmentConfigurationAttributes.None,
-    val capabilities: KotlinGradleFragmentConfigurationCapabilities<T> = KotlinGradleFragmentConfigurationCapabilities.None,
     val artifacts: KotlinGradleFragmentConfigurationArtifacts<T> = KotlinGradleFragmentConfigurationArtifacts.None,
     val relations: KotlinGradleFragmentConfigurationRelation = KotlinGradleFragmentConfigurationRelation.None,
+    @property:AdvancedExternalVariantApi
+    val capabilities: KotlinGradleFragmentConfigurationCapabilities<T> = KotlinGradleFragmentConfigurationCapabilities.None,
 )
 
 /* Internal abbreviation */
@@ -45,5 +47,6 @@ operator fun <T : KotlinGradleFragment> KotlinGradleFragmentConfigurationDefinit
 operator fun <T : KotlinGradleFragment> KotlinGradleFragmentConfigurationDefinition<T>.plus(other: FragmentArtifacts<T>):
         KotlinGradleFragmentConfigurationDefinition<T> = copy(artifacts = artifacts + other)
 
+@AdvancedExternalVariantApi
 operator fun <T : KotlinGradleFragment> KotlinGradleFragmentConfigurationDefinition<T>.plus(other: FragmentCapabilities<T>):
         KotlinGradleFragmentConfigurationDefinition<T> = copy(capabilities = capabilities + other)