Add comment to TypeSystemCommonSuperTypesContext.checkRecursion

Related to KT-38544, KT-60581

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>,