[Gradle] Add documentation to KotlinTargetHierarchyBuilder.Root functions
^KT-58209 Verification Pending
diff --git a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/KotlinTargetHierarchyBuilder.kt b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/KotlinTargetHierarchyBuilder.kt
index a5d02d7..0aede43 100644
--- a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/KotlinTargetHierarchyBuilder.kt
+++ b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/KotlinTargetHierarchyBuilder.kt
@@ -9,9 +9,87 @@
@ExperimentalKotlinGradlePluginApi
interface KotlinTargetHierarchyBuilder {
+ @KotlinTargetsDsl
+ @ExperimentalKotlinGradlePluginApi
interface Root : KotlinTargetHierarchyBuilder {
+ /**
+ * Defines the trees that the described hierarchy is applied to.
+ * ### Example 1: Only apply a hierarchy for the "main" and "test" [KotlinTargetHierarchy.SourceSetTree]
+ *
+ * ```kotlin
+ * targetHierarchy.custom {
+ * sourceSetTrees(SourceSetTree.main, SourceSetTree.test)
+ * common {
+ * withJvm()
+ * group("ios") {
+ * withIos()
+ * }
+ * }
+ * }
+ *```
+ *
+ * Will create the following trees given an iosX64(), iosArm64() and jvm() target:
+ * ```
+ * "main" "test"
+ * commonMain commonTest
+ * | |
+ * +----+-----+ +----+-----+
+ * | | | |
+ * iosMain jvmMain iosTest jvmTest
+ * | |
+ * +---+----+ +---+----+
+ * | | | |
+ * iosX64Main iosArm64Main iosX64Test iosArm64Test
+ * ```
+ *
+ * ### Example 2:
+ * Using a different hierarchy for "main" and "test"
+ *```kotlin
+ * targetHierarchy.custom {
+ * sourceSetTrees(SourceSetTree.main) // ! <- only applied to the "main" tree
+ * common {
+ * withJvm()
+ * group("ios") {
+ * withIos()
+ * }
+ * }
+ * }
+ *
+ * targetHierarchy.custom {
+ * sourceSetTrees(SourceSetTree.test) // ! <- only applied to the "test" tree
+ * common {
+ * withJvm()
+ * withIos()
+ * }
+ * }
+ * ```
+ *
+ * Will create the following trees given an iosX64(), iosArm64() and jvm() target:
+ * ```
+ * "main" "test"
+ * commonMain commonTest
+ * | |
+ * +----+-----+ +-----------+-----------+
+ * | | | | |
+ * iosMain jvmMain iosX64Test iosArm64Test jvmTest
+ * |
+ * +---+----+
+ * | |
+ * iosX64Main iosArm64Main
+ * ```
+ */
fun sourceSetTrees(vararg tree: KotlinTargetHierarchy.SourceSetTree)
+
+ /**
+ * Will add the given [tree]s into for this descriptor.
+ * @see sourceSetTrees
+ */
fun withSourceSetTree(vararg tree: KotlinTargetHierarchy.SourceSetTree)
+
+ /**
+ * Will remove the given [tree]s from this descriptor
+ * @see sourceSetTrees
+ */
fun excludeSourceSetTree(vararg tree: KotlinTargetHierarchy.SourceSetTree)
}
