diff --git a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/KotlinHierarchyTemplate.kt b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/KotlinHierarchyTemplate.kt
index 1bb11fac8dd..15f9f94cd29 100644
--- a/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/KotlinHierarchyTemplate.kt
+++ b/libraries/tools/kotlin-gradle-plugin-api/src/common/kotlin/org/jetbrains/kotlin/gradle/plugin/KotlinHierarchyTemplate.kt
@@ -12,25 +12,13 @@ import org.jetbrains.kotlin.gradle.InternalKotlinGradlePluginApi
 sealed interface KotlinHierarchyTemplate {
     companion object Templates {
         /**
-         * Set's up a 'natural'/'default' hierarchy within [KotlinTarget]'s, inside the project.
-         *
-         * #### Example 1
-         *
-         * ```kotlin
-         * kotlin {
-         *     applyDefaultHierarchyTemplate() // <- position of this call is not relevant!
-         *
-         *     iosX64()
-         *     iosArm64()
-         *     linuxX64()
-         *     linuxArm64()
-         * }
-         * ```
-         *
-         * Will create the following SourceSets:
-         * `[iosMain, iosTest, appleMain, appleTest, linuxMain, linuxTest, nativeMain, nativeTest]
-         *
+         * Default hierarchy for Kotlin Multiplatform projects.
+         * This hierarchy template will be applied to projects 'by default' if the project does not opt-out
+         * and is compatible.
          *
+         * Incompatible projects include:
+         *  - projects that setup custom dependsOn edges
+         *  - projects that define custom target names matching one of the shared source sets (e.g. linuxX64("linux"))
          * Hierarchy:
          * ```
          *                                                                     common