[Gradle] ExternalTargetApi: Check-in/Document createExternalKotlinTarget

KT-55524

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

@@ -13,6 +13,7 @@ import org.gradle.api.attributes.Usage
 import org.gradle.jvm.tasks.Jar
 import org.jetbrains.kotlin.gradle.ExternalKotlinTargetApi
 import org.jetbrains.kotlin.gradle.dsl.KotlinMultiplatformExtension
+import org.jetbrains.kotlin.gradle.plugin.KotlinTarget
 import org.jetbrains.kotlin.gradle.plugin.ide.kotlinIdeMultiplatformImport
 import org.jetbrains.kotlin.gradle.plugin.mpp.KotlinUsages
 import org.jetbrains.kotlin.gradle.plugin.mpp.configureSourcesPublicationAttributes
@@ -22,6 +23,13 @@ import org.jetbrains.kotlin.gradle.utils.lowerCamelCaseName
 import org.jetbrains.kotlin.gradle.utils.markConsumable
 import org.jetbrains.kotlin.gradle.utils.named
 
+/**
+ * Creates an adhoc/external Kotlin Target which can be maintained and evolved outside the kotlin.git repository.
+ * The target will be created adhering to the configuration provided by the [descriptor].
+ * The instance will be backed by an internal implementation of [KotlinTarget]
+ * The instance will be created using the [ExternalKotlinTargetDescriptor.targetFactory] which will have to inject the backing
+ * internal implementation using the [DecoratedExternalKotlinTarget.Delegate] into [DecoratedExternalKotlinTarget]
+ */
 @ExternalKotlinTargetApi
 fun <T : DecoratedExternalKotlinTarget> KotlinMultiplatformExtension.createExternalKotlinTarget(
     descriptor: ExternalKotlinTargetDescriptor<T>
@@ -91,6 +99,9 @@ fun <T : DecoratedExternalKotlinTarget> KotlinMultiplatformExtension.createExter
     return decorated
 }
 
+/**
+ * @see createExternalKotlinTarget
+ */
 @ExternalKotlinTargetApi
 fun <T : DecoratedExternalKotlinTarget> KotlinMultiplatformExtension.createExternalKotlinTarget(
     descriptor: ExternalKotlinTargetDescriptorBuilder<T>.() -> Unit