Add comments describing the semantics of an ATNConfig set with partially predicated alts in ParserATNSimulator

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

@@ -581,11 +581,11 @@ public class ParserATNSimulator<Symbol extends Token> extends ATNSimulator {
 						return predictedAlt;
 					}
 
-					if (D.prediction == ATN.INVALID_ALT_NUMBER) {
+					// Consistency check - the DFAState should not have a "fallback"
-						throw noViableAlt(input, outerContext, D.configset, startIndex);
+					// prediction specified for the case where no predicates succeed.
-					}
+					assert D.prediction == ATN.INVALID_ALT_NUMBER;
 
-					predictedAlt = D.prediction;
+					throw noViableAlt(input, outerContext, D.configset, startIndex);
 				}
 			}
 
@@ -754,6 +754,18 @@ public class ParserATNSimulator<Symbol extends Token> extends ATNSimulator {
 												  int nalts)
 	{
 		// REACH=[1|1|[]|0:0, 1|2|[]|0:1]
+
+		/* altToPred starts as an array of all null contexts. The entry at index i
+		 * corresponds to alternative i. altToPred[i] may have one of three values:
+		 *   1. null: no ATNConfig c is found such that c.alt==i
+		 *   2. SemanticContext.NONE: At least one ATNConfig c exists such that
+		 *      c.alt==i and c.semanticContext==SemanticContext.NONE. In other words,
+		 *      alt i has at least one unpredicated config.
+		 *   3. Non-NONE Semantic Context: There exists at least one, and for all
+		 *      ATNConfig c such that c.alt==i, c.semanticContext!=SemanticContext.NONE.
+		 *
+		 * From this, it is clear that NONE||anything==NONE.
+		 */
 		SemanticContext[] altToPred = new SemanticContext[nalts +1];
 		int n = altToPred.length;
 		for (ATNConfig c : configs) {

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

@@ -194,6 +194,10 @@ public abstract class SemanticContext {
 		return new AND(a, b);
 	}
 
+	/**
+	 *
+	 *  @see ParserATNSimulator#getPredsForAmbigAlts
+	 */
 	public static SemanticContext or(SemanticContext a, SemanticContext b) {
 		if ( a == null ) return b;
 		if ( b == null ) return a;