From edbf5c5cd806693a37e5b3748ce5c9a9bb1f3d34 Mon Sep 17 00:00:00 2001
From: "sebastian.sellmair" <sebastian.sellmair@jetbrains.com>
Date: Tue, 8 Mar 2022 16:01:09 +0100
Subject: [PATCH] [KPM] Document IdeaKotlinProjectModelBuilder

KT-51386
---
 .../kpm/idea/IdeaKotlinProjectModelBuilder.kt | 54 ++++++++++++++++++-
 1 file changed, 53 insertions(+), 1 deletion(-)

diff --git a/libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/kpm/idea/IdeaKotlinProjectModelBuilder.kt b/libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/kpm/idea/IdeaKotlinProjectModelBuilder.kt
index d712628e87a..2a36acd3709 100644
--- a/libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/kpm/idea/IdeaKotlinProjectModelBuilder.kt
+++ b/libraries/tools/kotlin-gradle-plugin/src/main/kotlin/org/jetbrains/kotlin/gradle/kpm/idea/IdeaKotlinProjectModelBuilder.kt
@@ -22,25 +22,77 @@ internal interface IdeaKotlinProjectModelBuildingContext {
 }
 
 interface IdeaKotlinProjectModelBuilder {
-
+    /**
+     * Any [IdeaKotlinDependencyResolver] has to be registered for a given dependency resolution phase in which it participates
+     * The resolution phases will be executed in the order of their enum's ordinal.
+     */
     enum class DependencyResolutionPhase {
+        /**
+         * Generic phase intended to run before all other resolvers
+         */
         PreDependencyResolution,
+
+        /**
+         * Resolution phase intended to resolve project to project (source) dependencies
+         */
         SourceDependencyResolution,
+
+        /**
+         * Resolution phase intended to resolve binary dependencies (downloading and transforming from repositories)
+         */
         BinaryDependencyResolution,
+
+        /**
+         * Generic phase intended to run after all other resolvers.
+         */
         PostDependencyResolution
     }
 
+    /**
+     * Any [IdeaKotlinDependencyResolver] has to be registered specifying a certain resolution level.
+     * Generally, all resolvers registered in a given resolution level will work collaboratively, meaning the dependency resolution
+     * result is the aggregation of all resolvers running.
+     *
+     * However, only the resolvers in the highest resolution result will run e.g.
+     * If resolvers with level [Overwrite] are found, then only those will contribute to the dependency resolution.
+     * Otherwise, all [Default] resolvers will run.
+     */
     enum class DependencyResolutionLevel {
         Default, Overwrite
     }
 
+    /**
+     * Any [IdeaKotlinDependencyTransformer] has to be registered for a given transformation phase.
+     * The phases will be executed in the order of this enums ordinal.
+     */
     enum class DependencyTransformationPhase {
+        /**
+         * Generic dependency transformation phase, intended to run a transformation before all other transformers.
+         */
         PreDependencyTransformationPhase,
+
+        /**
+         * Dependency transformation phase that is free entirely free in its transformation type.
+         * Note: Adding dependencies to the resolution result might most likely better be modelled as [IdeaKotlinDependencyResolver]
+         */
         FreeDependencyTransformationPhase,
+
+        /**
+         * Special dependency transformation phase intended for filtering dependencies.
+         * This phase is guaranteed to run after the [FreeDependencyTransformationPhase] alongside other dependency filtering
+         * transformations. Adding filters here is the safest.
+         */
         DependencyFilteringPhase,
+
+        /**
+         * Generic dependency transformation phase, intended to run a transformation after all other transformers
+         */
         PostDependencyTransformationPhase
     }
 
+    /**
+     * Used for scoping [IdeaKotlinDependencyResolver], [IdeaKotlinDependencyTransformer] and [IdeaKotlinDependencyEffect]
+     */
     fun interface FragmentConstraint {
         operator fun invoke(fragment: KotlinGradleFragment): Boolean