Add docs to CandidateApplicability, remove DSL_SCOPE_VIOLATION

compiler/fir/semantics/src/org/jetbrains/kotlin/fir/resolve/calls/ResolutionDiagnostic.kt

@@ -129,7 +129,7 @@ class Unsupported(val message: String, val source: KtSourceElement? = null) : Re
 
 object PropertyAsOperator : ResolutionDiagnostic(K2_PROPERTY_AS_OPERATOR)
 
-class DslScopeViolation(val calleeSymbol: FirBasedSymbol<*>) : ResolutionDiagnostic(K2_DSL_SCOPE_VIOLATION)
+class DslScopeViolation(val calleeSymbol: FirBasedSymbol<*>) : ResolutionDiagnostic(RESOLVED_WITH_ERROR)
 
 class MultipleContextReceiversApplicableForExtensionReceivers : ResolutionDiagnostic(INAPPLICABLE)
 

compiler/frontend/src/org/jetbrains/kotlin/resolve/calls/util/resolvedCallUtil.kt

@@ -124,7 +124,7 @@ fun ResolvedCall<*>.hasInferredReturnType(): Boolean {
 fun CandidateApplicability.toResolutionStatus(): ResolutionStatus = when (this) {
     CandidateApplicability.RESOLVED,
     CandidateApplicability.RESOLVED_LOW_PRIORITY,
-    CandidateApplicability.K1_RESOLVED_WITH_ERROR,
+    CandidateApplicability.RESOLVED_WITH_ERROR,
     CandidateApplicability.RESOLVED_NEED_PRESERVE_COMPATIBILITY -> ResolutionStatus.SUCCESS
     CandidateApplicability.INAPPLICABLE_WRONG_RECEIVER -> ResolutionStatus.RECEIVER_TYPE_ERROR
     CandidateApplicability.UNSAFE_CALL -> ResolutionStatus.UNSAFE_CALL_ERROR

compiler/resolution.common/src/org/jetbrains/kotlin/resolve/calls/tower/CandidateApplicability.kt

@@ -6,32 +6,119 @@
 package org.jetbrains.kotlin.resolve.calls.tower
 
 enum class CandidateApplicability {
-    K1_RESOLVED_TO_SAM_WITH_VARARG, // migration warning up to 1.5 (when resolve to function with SAM conversion and array without spread as vararg)
+    /**
-    HIDDEN, // removed from resolve (should get UNRESOLVED_REFERENCE, used for HIDDEN deprecations and similar things)
+     * Special applicability for migration warning up to 1.5.
-    K2_VISIBILITY_ERROR, // problems with visibility (should get INVISIBLE_REFERENCE)
+     * Used when resolved to function with SAM conversion and array without spread as vararg.
-    K2_UNSUPPORTED, // unsupported feature
+     */
-    INAPPLICABLE_WRONG_RECEIVER, // receiver not matched
+    K1_RESOLVED_TO_SAM_WITH_VARARG,
-    INAPPLICABLE_ARGUMENTS_MAPPING_ERROR, // arguments not mapped to parameters (i.e. different size of arguments and parameters)
-    INAPPLICABLE, // arguments have wrong types
-    K2_NO_COMPANION_OBJECT, // Classifier does not have a companion object
-    K1_IMPOSSIBLE_TO_GENERATE, // access to outer class from nested
-    K1_RUNTIME_ERROR, // TODO: FE 1.0 uses this as catch-all for all other errors. Consider re-assigning those diagnostics.
-    UNSAFE_CALL, // receiver or argument nullability doesn't match
-    UNSTABLE_SMARTCAST, // unstable smart cast
-    CONVENTION_ERROR, // missing infix, operator etc (= no expected modifier)
 
-    K2_DSL_SCOPE_VIOLATION, // Skip other levels for DSL_SCOPE_VIOLATION because if the candidate is marked DSL_SCOPE_VIOLATION with an inner receiver, one should not keep going to outer receivers.
+    /**
+     * Candidate is removed from resolve due to SinceKotlin with later version or Deprecation with hidden level.
+     * Provokes UNRESOLVED_REFERENCE.
+     */
+    HIDDEN,
 
-    // Below has isSuccess = true
+    /**
+     * Candidate isn't visible. Provokes INVISIBLE_REFERENCE.
+     */
+    K2_VISIBILITY_ERROR,
+
+    /**
+     * Candidate could be successful but requires an unsupported feature.
+     * Reported for references to local variables in K2.
+     * Provokes UNSUPPORTED.
+     */
+    K2_UNSUPPORTED,
+
+    /**
+     * Candidate could be successful but receiver isn't matched
+     */
+    INAPPLICABLE_WRONG_RECEIVER,
+
+    /**
+     * Candidate could be successful but arguments not mapped to parameters (i.e. different size of arguments and parameters)
+     */
+    INAPPLICABLE_ARGUMENTS_MAPPING_ERROR,
+
+    /**
+     * Candidate could be successful but arguments have wrong types (or other general inapplicability)
+     */
+    INAPPLICABLE,
+
+    /**
+     * Candidate could be successful but uses some non-object classifier without companion object as a variable.
+     */
+    K2_NO_COMPANION_OBJECT,
+
+    /**
+     * Candidate could be successful but requires access to outer class from nested (non-inner)
+     */
+    K1_IMPOSSIBLE_TO_GENERATE,
+
+    // TODO: Consider re-assigning this diagnostics (K1_RUNTIME_ERROR)
+
+    /**
+     * This applicability is used in K1 as a catch-all for all other errors.
+     */
+    K1_RUNTIME_ERROR,
+
+    /**
+     * Candidate could be successful but receiver (or argument?) nullability doesn't match
+     */
+    UNSAFE_CALL,
+
+    /**
+     * Candidate could be successful but requires unstable smart cast.
+     */
+    UNSTABLE_SMARTCAST,
+
+    /**
+     * Candidate could be successful but does not obey conventions.
+     * E.g. infix / operator / etc are missed (= no expected modifier).
+     */
+    CONVENTION_ERROR,
+
+    // Everything below has isSuccess = true (RESOLVED_WITH_ERROR is an exception)
+
+    /**
+     * Candidate is successful but has low priority.
+     * Tower resolve proceeds to next levels.
+     */
     RESOLVED_LOW_PRIORITY,
-    K2_PROPERTY_AS_OPERATOR, // using property of functional type as an operator. From resolution perspective, this is considered successful.
-    RESOLVED_NEED_PRESERVE_COMPATIBILITY, // call resolved successfully, but using new features that change resolve
 
-    // Tower resolve does not go to further scopes if candidate with applicability below is found
+    /**
+     * Candidate is successful but uses property of functional type as an operator.
+     * Tower resolve proceeds to next levels.
+     */
+    K2_PROPERTY_AS_OPERATOR,
 
-    K2_SYNTHETIC_RESOLVED, // used in K2 for (Java) synthetic discrimination at the same level
+    /**
-    K1_RESOLVED_WITH_ERROR, // call has error, but it is still successful from resolution perspective
+     * Candidate is successful but uses new features that change resolve.
-    RESOLVED, // call success or has uncompleted inference or in other words possible successful candidate
+     * Tower resolve proceeds to next levels.
+     */
+    RESOLVED_NEED_PRESERVE_COMPATIBILITY,
+
+    // Everything below has shouldStopResolve = true
+    // (Tower resolve does not go to further scopes if candidate with applicability below is found)
+
+    /**
+     * Successful but synthetic candidate.
+     * Used in K2 for (Java) synthetic discrimination at the same level.
+     */
+    K2_SYNTHETIC_RESOLVED,
+
+    /**
+     * Candidate has some error, but it is still successful from resolution perspective.
+     * This means that tower resolve stops with this applicability.
+     * However, error will be reported.
+     * This is the only applicability that stops resolve but provokes an error.
+     */
+    RESOLVED_WITH_ERROR,
+
+    /**
+     * Candidate is successful or has uncompleted inference (so possibly successful).
+     */
+    RESOLVED,
 }
 
 /**
@@ -39,11 +126,11 @@ enum class CandidateApplicability {
  * Note that it does not necessarily mean tower resolve should stop on this candidate.
  */
 val CandidateApplicability.isSuccess: Boolean
-    get() = this >= CandidateApplicability.RESOLVED_LOW_PRIORITY && this != CandidateApplicability.K1_RESOLVED_WITH_ERROR
+    get() = this >= CandidateApplicability.RESOLVED_LOW_PRIORITY && this != CandidateApplicability.RESOLVED_WITH_ERROR
 
 /**
  * This property determines that tower resolve should stop on the candidate/group with this applicability
  * and should not go to further scope levels. Note that candidate can still have error(s).
  */
 val CandidateApplicability.shouldStopResolve: Boolean
-    get() = this == CandidateApplicability.K2_DSL_SCOPE_VIOLATION || this >= CandidateApplicability.K2_SYNTHETIC_RESOLVED
+    get() = this >= CandidateApplicability.K2_SYNTHETIC_RESOLVED

compiler/resolution/src/org/jetbrains/kotlin/resolve/calls/model/KotlinCallDiagnostics.kt

@@ -157,7 +157,7 @@ class NotCallableExpectedType(
 ) : CallableReferenceInapplicableDiagnostic(argument)
 
 class AdaptedCallableReferenceIsUsedWithReflection(val argument: CallableReferenceResolutionAtom) :
-    CallableReferenceInapplicableDiagnostic(argument, K1_RESOLVED_WITH_ERROR)
+    CallableReferenceInapplicableDiagnostic(argument, RESOLVED_WITH_ERROR)
 
 // SmartCasts
 class SmartCastDiagnostic(
@@ -194,7 +194,7 @@ class UnstableSmartCastResolutionError(
 class UnstableSmartCastDiagnosticError(
     argument: ExpressionKotlinCallArgument,
     targetType: UnwrappedType,
-) : UnstableSmartCast(argument, targetType, K1_RESOLVED_WITH_ERROR)
+) : UnstableSmartCast(argument, targetType, RESOLVED_WITH_ERROR)
 
 class UnsafeCallError(
     val receiver: SimpleKotlinCallArgument,
@@ -282,7 +282,7 @@ class ResolvedToSamWithVarargDiagnostic(val argument: KotlinCallArgument) : Kotl
 class NotEnoughInformationForLambdaParameter(
     val lambdaArgument: LambdaKotlinCallArgument,
     val parameterIndex: Int
-) : KotlinCallDiagnostic(K1_RESOLVED_WITH_ERROR) {
+) : KotlinCallDiagnostic(RESOLVED_WITH_ERROR) {
     override fun report(reporter: DiagnosticReporter) {
         reporter.onCallArgument(lambdaArgument, this)
     }

compiler/resolution/src/org/jetbrains/kotlin/resolve/calls/tower/ImplicitScopeTower.kt

@@ -114,13 +114,13 @@ abstract class ResolutionDiagnostic(candidateApplicability: CandidateApplicabili
     }
 }
 
-class ContextReceiverAmbiguity : ResolutionDiagnostic(K1_RESOLVED_WITH_ERROR) {
+class ContextReceiverAmbiguity : ResolutionDiagnostic(RESOLVED_WITH_ERROR) {
     override fun report(reporter: DiagnosticReporter) {
         reporter.onCall(this)
     }
 }
 
-class UnsupportedContextualDeclarationCall : ResolutionDiagnostic(K1_RESOLVED_WITH_ERROR) {
+class UnsupportedContextualDeclarationCall : ResolutionDiagnostic(RESOLVED_WITH_ERROR) {
     override fun report(reporter: DiagnosticReporter) {
         reporter.onCall(this)
     }