From 2ec76110b093f24510b6895f11082b68d5a57cc6 Mon Sep 17 00:00:00 2001
From: Sebastian Sellmair <sebastian.sellmair@jetbrains.com>
Date: Wed, 19 Apr 2023 14:54:59 +0200
Subject: [PATCH] [Gradle] ExternalTargetApi: Check-in/Document
 createCompilation

KT-55524
---
 .../external/createExternalKotlinCompilation.kt  | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/external/createExternalKotlinCompilation.kt b/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/external/createExternalKotlinCompilation.kt
index 397dc97bec0..aba11fb0cd6 100644
--- a/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/external/createExternalKotlinCompilation.kt
+++ b/libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/mpp/external/createExternalKotlinCompilation.kt
@@ -17,6 +17,17 @@ import org.jetbrains.kotlin.gradle.plugin.mpp.decoratedInstance
 import org.jetbrains.kotlin.gradle.plugin.mpp.external.ExternalDecoratedKotlinCompilation.Delegate
 import org.jetbrains.kotlin.gradle.tasks.KotlinTasksProvider
 
+/**
+ *  Creates a compilation for External Kotlin Targets adhering to the configuration provided in the [descriptor]
+ *  - The _kind_ of compilation will be chosen automatically by the specified [DecoratedExternalKotlinTarget.platformType]
+ *  - The compilation will use the [ExternalKotlinCompilationDescriptor.defaultSourceSet] as its (default) source set
+ *  - The compilation wil reference the compile task using the [ExternalKotlinCompilationDescriptor.compileTaskName] if specified
+ *  - The compilation will reference the compile all task name using the[ExternalKotlinCompilationDescriptor.compileAllTaskName] if specified
+ *  - Compilations .associateWith calls will be handled by the [ExternalKotlinCompilationDescriptor.compilationAssociator] if specified
+ *  - An additional friendArtifactResolver will be respected if the [ExternalKotlinCompilationDescriptor.friendArtifactResolver] is specified
+ *  - The [ExternalKotlinCompilationDescriptor.configure] method will be called before the compilation is available in [KotlinTarget.compilations]
+ *  container
+ */
 @ExternalKotlinTargetApi
 fun <T : ExternalDecoratedKotlinCompilation> DecoratedExternalKotlinTarget.createCompilation(
     descriptor: ExternalKotlinCompilationDescriptor<T>
@@ -67,6 +78,9 @@ fun <T : ExternalDecoratedKotlinCompilation> DecoratedExternalKotlinTarget.creat
     return decoratedCompilation
 }
 
+/**
+ * @see createCompilation
+ */
 @ExternalKotlinTargetApi
 fun <T : ExternalDecoratedKotlinCompilation> DecoratedExternalKotlinTarget.createCompilation(
     descriptor: ExternalKotlinCompilationDescriptorBuilder<T>.() -> Unit
@@ -74,8 +88,6 @@ fun <T : ExternalDecoratedKotlinCompilation> DecoratedExternalKotlinTarget.creat
     return createCompilation(ExternalKotlinCompilationDescriptor(descriptor))
 }
 
-
-@OptIn(ExternalKotlinTargetApi::class)
 private fun DecoratedExternalKotlinTarget.setupCompileTask(
     compilation: ExternalDecoratedKotlinCompilation
 ) {