[Gradle] Add KDoc for KotlinHierarchyTemplate

^KT-58858 In Progress

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

@@ -10,19 +10,31 @@ import org.jetbrains.kotlin.gradle.InternalKotlinGradlePluginApi
 
 
 /**
- * @suppress TODO: KT-58858 add documentation
+ * Defines a hierarchy of [KotlinSourceSets][KotlinSourceSet] in a multiplatform project.
+ *
+ * By default, the [default template][KotlinHierarchyTemplate.default] is applied in multiplatform projects (with some exceptions,
+ * check [Templates.default] for more details).
+ *
+ * To create a custom template, use the `kotlin.applyHierarchyTemplate { }` method.
  */
 sealed interface KotlinHierarchyTemplate {
+
+    /**
+     * Pre-defined [KotlinSourceSets][KotlinSourceSet] hierarchy templates.
+     */
     companion object Templates {
         /**
-         * 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.
+         * The default [KotlinSourceSets][KotlinSourceSet] hierarchy template for Kotlin Multiplatform projects.
+         *
+         * This hierarchy template is applied to projects 'by default' if they are compatible
+         * unless the project opts out via the Gradle property `kotlin.mpp.applyDefaultHierarchyTemplate=false`,
+         * or defines a custom [KotlinHierarchyTemplate] (for example, via `kotlin.applyHierarchyTemplate { .. }`).
          *
          * 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:
+         *  - Projects that configure custom [KotlinSourceSet.dependsOn] edges.
+         *  - Projects that define custom target names matching one of the shared source sets. For example, `kotlin.linuxX64("linux")`.
+         *
+         * The default hierarchy is:
          * ```
          *                                                                     common
          *                                                                        |
@@ -55,7 +67,7 @@ EXPERIMENTAL API
  */
 
 /**
- * @suppress TODO: KT-58858 add documentation
+ * Creates a new [KotlinHierarchyTemplate] using inputs provided via the [describe] definition.
  */
 @ExperimentalKotlinGradlePluginApi
 fun KotlinHierarchyTemplate(
@@ -65,7 +77,8 @@ fun KotlinHierarchyTemplate(
 }
 
 /**
- * @suppress TODO: KT-58858 add documentation
+ * Creates a new [KotlinHierarchyTemplate] by extending the existing one and using inputs provided via the [describe]
+ * definition.
  */
 @ExperimentalKotlinGradlePluginApi
 fun KotlinHierarchyTemplate.extend(describe: KotlinHierarchyBuilder.Root.() -> Unit): KotlinHierarchyTemplate {
@@ -80,19 +93,25 @@ INTERNAL API
  */
 
 /**
- * @suppress TODO: KT-58858 add documentation
+ * @suppress
  */
 @InternalKotlinGradlePluginApi
 @OptIn(ExperimentalKotlinGradlePluginApi::class)
 fun KotlinHierarchyBuilder.Root.applyHierarchyTemplate(template: KotlinHierarchyTemplate) {
     template.impl.layout(this)
 }
 
+/**
+ * @suppress
+ */
 internal val KotlinHierarchyTemplate.impl
     get() = when (this) {
         is KotlinHierarchyTemplateImpl -> this
     }
 
+/**
+ * @suppress
+ */
 @OptIn(ExperimentalKotlinGradlePluginApi::class)
 internal class KotlinHierarchyTemplateImpl(
     private val describe: KotlinHierarchyBuilder.Root.() -> Unit,
@@ -111,10 +130,10 @@ internal class KotlinHierarchyTemplateImpl(
     }
 }
 
-/*
-Default Hierarchy Template Implementation
+/**
+ * @suppress
+ * The default hierarchy template implementation
  */
-
 @OptIn(ExperimentalKotlinGradlePluginApi::class)
 private val defaultKotlinHierarchyTemplate = KotlinHierarchyTemplate {
     /* natural hierarchy is only applied to default 'main'/'test' compilations (by default) */