Add documentation to healAmbiguous

Author: EugeneFlesselle

compiler/src/dotty/tools/dotc/typer/Implicits.scala

@@ -1451,11 +1451,20 @@ trait Implicits:
               def betterThanAll(newCand: RefAndLevel, disambiguate: Boolean): Boolean =
                 ambiguousCands.forall(compareAlternatives(newCand, _, disambiguate) > 0)
 
+              inline def betterByCurrentScheme(newCand: RefAndLevel): Boolean =
+                if isWarnPriorityChangeVersion then
+                  // newCand may have only been kept in pending because it was better in the other priotization scheme.
+                  // If that candidate produces a SearchSuccess, disambiguate will return it as the found SearchResult.
+                  // We must now recheck it was really better than the ambigous candidates we are recovering from,
+                  // under the rules of the current scheme, which are applied when disambiguate = true.
+                  betterThanAll(newCand, disambiguate = true)
+                else true
+
               val newPending = remaining.filter(betterThanAll(_, disambiguate = false))
               rank(newPending, fail, Nil) match
-                case found: SearchSuccess
-                  if !isWarnPriorityChangeVersion || betterThanAll(found, disambiguate = true) => found
+                case found: SearchSuccess if betterByCurrentScheme(cand) => found
                 case _ => fail
+            end healAmbiguous
 
             negateIfNot(tryImplicit(cand, contextual)) match {
               case fail: SearchFailure =>