From 4da7453a7bedafcfe510dd1872022f2e7c4dd4ed Mon Sep 17 00:00:00 2001
From: Mikhail Glukhikh <mikhail.glukhikh@jetbrains.com>
Date: Wed, 4 Oct 2023 10:03:19 +0200
Subject: [PATCH] Add comment to
 TypeSystemCommonSuperTypesContext.checkRecursion

Related to KT-38544, KT-60581
---
 .../calls/NewCommonSuperTypeCalculator.kt       | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/compiler/resolution.common/src/org/jetbrains/kotlin/resolve/calls/NewCommonSuperTypeCalculator.kt b/compiler/resolution.common/src/org/jetbrains/kotlin/resolve/calls/NewCommonSuperTypeCalculator.kt
index 033d86ddd77..38eebdbeadd 100644
--- a/compiler/resolution.common/src/org/jetbrains/kotlin/resolve/calls/NewCommonSuperTypeCalculator.kt
+++ b/compiler/resolution.common/src/org/jetbrains/kotlin/resolve/calls/NewCommonSuperTypeCalculator.kt
@@ -375,6 +375,23 @@ object NewCommonSuperTypeCalculator {
         return capturedType.typeConstructor().projection()
     }
 
+    /**
+     * This function returns true in case of detected recursion in type arguments.
+     *
+     * For situations with self type arguments (or similar ones), the call of this function
+     * prevents too deep type argument analysis during super type calculation.
+     * Typical examples use something like this interface in hierarchy:
+     * ```
+     * interface Some<T : Some<T>>
+     * ```
+     * From point of view of this function we have here something like `Some<CapturedType>` in [originalTypesForCst],
+     * and the captured type in argument has the same `Some<CapturedType>` as its constructor supertype.
+     *
+     * See also the test 'multirecursion.kt' and comment to the fix of [KT-38544](https://youtrack.jetbrains.com/issue/KT-38544):
+     * for single super type constructor create star projection argument when types for that argument are equal to the original types.
+     * Captured star projections are replaced with their corresponding supertypes during this check.
+     * The check is skipped for contravariant parameters, for which recursive cst calculation never happens.
+     */
     private fun TypeSystemCommonSuperTypesContext.checkRecursion(
         originalTypesForCst: List<SimpleTypeMarker>,
         typeArgumentsForSuperConstructorParameter: List<TypeArgumentMarker>,