[Gradle] Rename KotlinTargetHierarchy.ModuleName to .SourceSetTree

^KT-58209 Verification Pending

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/KotlinTargetHierarchy.kt

@@ -7,11 +7,60 @@ package org.jetbrains.kotlin.gradle.plugin
 
 interface KotlinTargetHierarchy {
 
-    class ModuleName(val name: String) {
+    /**
+     * When applying any [KotlinTargetHierarchyDescriptor] (e.g. by calling `targetHierarchy.default()`), the descriptor will
+     * be applied on individual compilations, creating multiple trees of shared SourceSets.
+     *
+     * The name of given shared source set within the target hierarchy will be built by
+     * `lowerCamelCase(nameOfGroup, nameOfSourceSetTree)`
+     * So for the 'common' group within the 'main' tree the shared SourceSet name will be 'commonMain'
+     *
+     * The most default case will create two well known SourceSetTrees:
+     * - The `main` tree with `commonMain` as its root SourceSet
+     * - The `test` tree with `commonTest` as its root SourceSet
+     *
+     * e.g.
+     * ```kotlin
+     * kotlin {
+     *     targetHierarchy.default()
+     *     jvm()
+     *     iosX64()
+     *     iosArm64()
+     * }
+     * ```
+     *
+     * will create two SourceSetTrees: "main" and "test"
+     * ```
+     *                    "main"                               "test"
+     *
+     *                  commonMain                           commonTest
+     *                      |                                    |
+     *                      |                                    |
+     *           +----------+----------+              +----------+----------+
+     *           |                     |              |                     |
+     *          ...                  jvmMain         ...                  jvmTest
+     *           |                                    |
+     *           |                                    |
+     *         iosMain                              iosTest
+     *           |                                    |
+     *      +----+-----+                         +----+-----+
+     *      |          |                         |          |
+     * iosX64Main   iosArm64Main            iosX64Test   iosArm64Test
+     * ```
+     *
+     *
+     * Usually, the name of the compilation correlates to the name of the SourceSetTree:
+     * As seen in the previous example, the "main" tree under the "commonMain" root contains all 'main' compilations of the projects
+     * targets. The "test" tree under the "commonTest" root contains all 'test' compilations of the projects targets.
+     *
+     * There are some exceptions, where the name of the compilations cannot be chosen by the user directly (Android)
+     * In this case, the name of the SourceSet can be configured outside the target hierarchy DSL.
+     */
+    class SourceSetTree(val name: String) {
         override fun toString(): String = name
 
         override fun equals(other: Any?): Boolean {
-            if (other !is ModuleName) return false
+            if (other !is SourceSetTree) return false
             return this.name == other.name
         }
 
@@ -20,11 +69,34 @@ interface KotlinTargetHierarchy {
         }
 
         companion object {
-            val main = ModuleName("main")
-            val test = ModuleName("test")
-            val unitTest = ModuleName("unitTest")
-            val integrationTest = ModuleName("integrationTest")
-            val instrumentedTest = ModuleName("instrumentedTest")
+            /**
+             * The 'main' SourceSetTree. Typically, with 'commonMain' as the root SourceSet
+             */
+            val main = SourceSetTree("main")
+
+            /**
+             * The 'test' SourceSetTree. Typically, with 'commonTest' as the root SourceSet
+             */
+            val test = SourceSetTree("test")
+
+            /**
+             * Special pre-defined SourceSetTree: Can be used to introduce a new tree with 'commonUnitTest' as the root SourceSet
+             * e.g. relevant for organising Android unitTest compilations/SourceSets
+             */
+            val unitTest = SourceSetTree("unitTest")
+
+
+            /**
+             * Special pre-defined SourceSetTree: Can be used to introduce a new tree with 'commonInstrumentedTest' as the root SourceSet
+             * e.g. relevant for organising Android instrumented compilations/SourceSets
+             */
+            val instrumentedTest = SourceSetTree("instrumentedTest")
+
+
+            /**
+             * Special pre-defined SourceSetTree: Can be used to introduce a new tree with 'commonIntegrationTest' as root SourceSEt
+             */
+            val integrationTest = SourceSetTree("integrationTest")
         }
     }
 }

libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/KotlinTargetHierarchyBuilder.kt

@@ -10,9 +10,9 @@ import org.jetbrains.kotlin.konan.target.DEPRECATED_TARGET_MESSAGE
 interface KotlinTargetHierarchyBuilder {
 
     interface Root : KotlinTargetHierarchyBuilder {
-        fun modules(vararg module: KotlinTargetHierarchy.ModuleName)
-        fun withModule(vararg module: KotlinTargetHierarchy.ModuleName)
-        fun excludeModule(vararg module: KotlinTargetHierarchy.ModuleName)
+        fun sourceSetTrees(vararg tree: KotlinTargetHierarchy.SourceSetTree)
+        fun withSourceSetTree(vararg tree: KotlinTargetHierarchy.SourceSetTree)
+        fun excludeSourceSetTree(vararg tree: KotlinTargetHierarchy.SourceSetTree)
     }
 
     /* Declaring groups */