[Gradle] ExternalTargetApi: Check-in/Document IdeDependencyTransformer

KT-55524

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

@@ -46,6 +46,17 @@ public final class org/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyResolverK
 	public static final fun plus (Lorg/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyResolver;Lorg/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyResolver;)Lorg/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyResolver;
 }
 
+public abstract interface class org/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyTransformer {
+	public abstract fun transform (Lorg/jetbrains/kotlin/gradle/plugin/KotlinSourceSet;Ljava/util/Set;)Ljava/util/Set;
+}
+
+public final class org/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyTransformerKt {
+	public static final fun IdeDependencyTransformer (Ljava/util/List;)Lorg/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyTransformer;
+	public static final fun IdeDependencyTransformer ([Lorg/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyTransformer;)Lorg/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyTransformer;
+	public static final fun plus (Lorg/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyTransformer;Lorg/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyTransformer;)Lorg/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyTransformer;
+	public static final fun withTransformer (Lorg/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyResolver;Lorg/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyTransformer;)Lorg/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyResolver;
+}
+
 public abstract interface class org/jetbrains/kotlin/gradle/plugin/ide/IdeMultiplatformImport {
 	public static final field Companion Lorg/jetbrains/kotlin/gradle/plugin/ide/IdeMultiplatformImport$Companion;
 	public static fun instance (Lorg/gradle/api/Project;)Lorg/jetbrains/kotlin/gradle/plugin/ide/IdeMultiplatformImport;

libraries/tools/kotlin-gradle-plugin/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/ide/IdeDependencyTransformer.kt

@@ -5,6 +5,7 @@
 
 package org.jetbrains.kotlin.gradle.plugin.ide
 
+import org.jetbrains.kotlin.gradle.ExternalKotlinTargetApi
 import org.jetbrains.kotlin.gradle.idea.tcs.IdeaKotlinDependency
 import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet
 
@@ -16,24 +17,46 @@ import org.jetbrains.kotlin.gradle.plugin.KotlinSourceSet
  *
  * Transformations can be scheduled in different phases see: [IdeMultiplatformImport.DependencyTransformationPhase]
  */
+@ExternalKotlinTargetApi
 fun interface IdeDependencyTransformer {
     fun transform(sourceSet: KotlinSourceSet, dependencies: Set<IdeaKotlinDependency>): Set<IdeaKotlinDependency>
 }
 
+/**
+ * Creates a [IdeDependencyResolver] which will invoke the given [transformer] right after resolving the dependencies from the
+ * receiver.
+ */
+@ExternalKotlinTargetApi
 fun IdeDependencyResolver.withTransformer(transformer: IdeDependencyTransformer) = IdeDependencyResolver { sourceSet ->
     transformer.transform(sourceSet, this@withTransformer.resolve(sourceSet))
 }
 
+/**
+ * Create a composite [IdeDependencyTransformer]
+ * `null` instances will just be ignored.
+ * The transformers will be invoked in the same order as specified to this function.
+ */
+@ExternalKotlinTargetApi
 fun IdeDependencyTransformer(
     transformers: List<IdeDependencyTransformer?>
 ): IdeDependencyTransformer = IdeCompositeDependencyTransformer(transformers.filterNotNull())
 
+/**
+ * Create a composite [IdeDependencyTransformer]
+ * `null` instances will just be ignored.
+ * The transformers will be invoked in the same order as specified to this function.
+ */
+@ExternalKotlinTargetApi
 fun IdeDependencyTransformer(
     vararg transformers: IdeDependencyTransformer?
 ): IdeDependencyTransformer = IdeDependencyTransformer(transformers.toList())
 
-operator fun IdeDependencyTransformer.plus(other: IdeDependencyTransformer):
+/**
-        IdeDependencyTransformer {
+ * Combines two [IdeDependencyResolver] into a single instance:
+ * This function will flatten the composite if either receiver or [other] transformer are already composite instances
+ */
+@ExternalKotlinTargetApi
+operator fun IdeDependencyTransformer.plus(other: IdeDependencyTransformer): IdeDependencyTransformer {
     if (this is IdeCompositeDependencyTransformer && other is IdeCompositeDependencyTransformer) {
         return IdeCompositeDependencyTransformer(this.transformers + other.transformers)
     }