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 a5d02d7952a..0aede436a99 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 @@ import org.jetbrains.kotlin.konan.target.DEPRECATED_TARGET_MESSAGE
 @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)
     }