[Gradle] ExternalTargetApi: Check-in/Document ExternalKotlinCompilationDescriptor

KT-55524

libraries/tools/kotlin-gradle-plugin/api/kotlin-gradle-plugin.api

@@ -241,6 +241,21 @@ public abstract interface class org/jetbrains/kotlin/gradle/plugin/mpp/external/
 	public abstract fun getFriendArtifactResolver ()Lorg/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinCompilationDescriptor$FriendArtifactResolver;
 }
 
+public abstract interface class org/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinCompilationDescriptor$CompilationAssociator {
+	public abstract fun associate (Lorg/jetbrains/kotlin/gradle/plugin/mpp/external/DecoratedExternalKotlinCompilation;Lorg/jetbrains/kotlin/gradle/plugin/mpp/external/DecoratedExternalKotlinCompilation;)V
+}
+
+public abstract interface class org/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinCompilationDescriptor$CompilationFactory {
+	public abstract fun create (Lorg/jetbrains/kotlin/gradle/plugin/mpp/external/DecoratedExternalKotlinCompilation$Delegate;)Lorg/jetbrains/kotlin/gradle/plugin/mpp/DecoratedKotlinCompilation;
+}
+
+public abstract interface class org/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinCompilationDescriptor$DecoratedKotlinCompilationFactory : org/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinCompilationDescriptor$CompilationFactory {
+}
+
+public abstract interface class org/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinCompilationDescriptor$FriendArtifactResolver {
+	public abstract fun resolveFriendPaths (Lorg/jetbrains/kotlin/gradle/plugin/mpp/external/DecoratedExternalKotlinCompilation;)Lorg/gradle/api/file/FileCollection;
+}
+
 public final class org/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinCompilationDescriptorBuilder {
 	public final fun configure (Lkotlin/jvm/functions/Function1;)Lorg/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinCompilationDescriptorBuilder;
 	public final fun getCompilationAssociator ()Lorg/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinCompilationDescriptor$CompilationAssociator;

libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/external/ExternalKotlinCompilationDescriptor.kt

@@ -7,11 +7,17 @@ package org.jetbrains.kotlin.gradle.plugin.mpp.external
 
 import org.gradle.api.file.FileCollection
 import org.jetbrains.kotlin.gradle.ExternalKotlinTargetApi
+import org.jetbrains.kotlin.gradle.plugin.KotlinCompilation
 import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet
+import org.jetbrains.kotlin.gradle.plugin.KotlinTarget
 import org.jetbrains.kotlin.gradle.plugin.mpp.DecoratedKotlinCompilation
 import org.jetbrains.kotlin.gradle.plugin.mpp.external.ExternalKotlinCompilationDescriptor.*
 import kotlin.properties.Delegates
 
+/**
+ * Describes how a compilation created for an external [KotlinTarget] should be created.
+ * @see createCompilation
+ */
 @ExternalKotlinTargetApi
 interface ExternalKotlinCompilationDescriptor<T : DecoratedExternalKotlinCompilation> {
 
@@ -22,16 +28,31 @@ interface ExternalKotlinCompilationDescriptor<T : DecoratedExternalKotlinCompila
         "Renamed to 'CompilationFactory'", level = DeprecationLevel.ERROR,
         replaceWith = ReplaceWith("CompilationFactory")
     )
+    @ExternalKotlinTargetApi
     fun interface DecoratedKotlinCompilationFactory<T : DecoratedKotlinCompilation<*>> : CompilationFactory<T>
 
+    /**
+     * Factory creating the decorated instance ([DecoratedExternalKotlinCompilation] using the backing implementation inside
+     * the [DecoratedExternalKotlinCompilation.Delegate]
+     */
+    @ExternalKotlinTargetApi
     fun interface CompilationFactory<T : DecoratedKotlinCompilation<*>> {
         fun create(delegate: DecoratedExternalKotlinCompilation.Delegate): T
     }
 
+    /**
+     * Providing an additional [FriendArtifactResolver] will allow to add 'friend artifacts' to the compilation
+     */
+    @ExternalKotlinTargetApi
     fun interface FriendArtifactResolver<T : DecoratedExternalKotlinCompilation> {
         fun resolveFriendPaths(compilation: T): FileCollection
     }
 
+    /**
+     * Implementing a [CompilationAssociator] allows for intercepting the [KotlinCompilation.associateWith] calls, effectively
+     * handling them on behalf of the authors of the external [KotlinTarget]
+     */
+    @ExternalKotlinTargetApi
     fun interface CompilationAssociator<T : DecoratedExternalKotlinCompilation> {
         fun associate(auxiliary: T, main: DecoratedExternalKotlinCompilation)
     }
@@ -93,7 +114,6 @@ class ExternalKotlinCompilationDescriptorBuilder<T : DecoratedExternalKotlinComp
     }
 }
 
-@ExternalKotlinTargetApi
 private data class ExternalKotlinCompilationDescriptorImpl<T : DecoratedExternalKotlinCompilation>(
     override val compilationName: String,
     override val compileTaskName: String?,