add Sam's comment.

runtime/Java/src/org/antlr/v4/runtime/atn/ParserATNSimulator.java

@@ -1166,6 +1166,64 @@ public class ParserATNSimulator extends ATNSimulator {
 		return pairs.toArray(new DFAState.PredPrediction[pairs.size()]);
 	}
 
+	/**
+	 * This method is used to improve the localization of error messages by
+	 * choosing an alternative rather than throwing a
+	 * {@link NoViableAltException} in particular prediction scenarios where the
+	 * {@link #ERROR} state was reached during ATN simulation.
+	 *
+	 * <p>
+	 * The default implementation of this method uses the following
+	 * algorithm to identify an ATN configuration which successfully parsed the
+	 * decision entry rule. Choosing such an alternative ensures that the
+	 * {@link ParserRuleContext} returned by the calling rule will be complete
+	 * and valid, and the syntax error will be reported later at a more
+	 * localized location.</p>
+	 *
+	 * <ul>
+	 * <li>If no configuration in {@code configs} reached the end of the
+	 * decision rule, return {@link ATN#INVALID_ALT_NUMBER}.</li>
+	 * <li>If all configurations in {@code configs} which reached the end of the
+	 * decision rule predict the same alternative, return that alternative.</li>
+	 * <li>If the configurations in {@code configs} which reached the end of the
+	 * decision rule predict multiple alternatives (call this <em>S</em>),
+	 * choose an alternative in the following order.
+	 * <ol>
+	 * <li>Filter the configurations in {@code configs} to only those
+	 * configurations which remain viable after evaluating semantic predicates.
+	 * If the set of these filtered configurations which also reached the end of
+	 * the decision rule is not empty, return the minimum alternative
+	 * represented in this set.</li>
+	 * <li>Otherwise, choose the minimum alternative in <em>S</em>.</li>
+	 * </ol>
+	 * </li>
+	 * </ul>
+	 *
+	 * <p>
+	 * In some scenarios, the algorithm described above could predict an
+	 * alternative which will result in a {@link FailedPredicateException} in
+	 * parser. Specifically, this could occur if the <em>only</em> configuration
+	 * capable of successfully parsing to the end of the decision rule is
+	 * blocked by a semantic predicate. By choosing this alternative within
+	 * {@link #adaptivePredict} instead of throwing a
+	 * {@link NoViableAltException}, the resulting
+	 * {@link FailedPredicateException} in the parser will identify the specific
+	 * predicate which is preventing the parser from successfully parsing the
+	 * decision rule, which helps developers identify and correct logic errors
+	 * in semantic predicates.
+	 * </p>
+	 *
+	 * @param input The input {@link TokenStream}
+	 * @param startIndex The start index for the current prediction, which is
+	 * the input index where any semantic context in {@code configs} should be
+	 * evaluated
+	 * @param configs The ATN configurations which were valid immediately before
+	 * the {@link #ERROR} state was reached
+	 *
+	 * @return The value to return from {@link #adaptivePredict}, or
+	 * {@link ATN#INVALID_ALT_NUMBER} if a suitable alternative was not
+	 * identified and {@link #adaptivePredict} should report an error instead.
+	 */
 	protected int getAltThatFinishedDecisionEntryRule(ATNConfigSet configs) {
 		IntervalSet alts = new IntervalSet();
 		for (ATNConfig c : configs) {