Updated documentation in LL1Analyzer

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

@@ -30,7 +30,6 @@
 
 package org.antlr.v4.runtime.atn;
 
-import org.antlr.v4.runtime.IntStream;
 import org.antlr.v4.runtime.RuleContext;
 import org.antlr.v4.runtime.Token;
 import org.antlr.v4.runtime.misc.IntervalSet;
@@ -43,7 +42,7 @@ import java.util.Set;
 
 public class LL1Analyzer {
 	/** Special value added to the lookahead sets to indicate that we hit
-	 *  a predicate during analysis if seeThruPreds==false.
+	 *  a predicate during analysis if {@code seeThruPreds==false}.
 	 */
 	public static final int HIT_PRED = Token.INVALID_TYPE;
 
@@ -53,8 +52,14 @@ public class LL1Analyzer {
 	public LL1Analyzer(@NotNull ATN atn) { this.atn = atn; }
 
 	/**
-	 * From an ATN state, {@code s}, find the set of all labels reachable from
+	 * Calculates the SLL(1) expected lookahead set for each outgoing transition
-	 * {@code s} at depth k. Only for DecisionStates.
+	 * of an {@link ATNState}. The returned array has one element for each
+	 * outgoing transition in {@code s}. If the closure from transition
+	 * <em>i</em> leads to a semantic predicate before matching a symbol, the
+	 * element at index <em>i</em> of the result will be {@code null}.
+	 *
+	 * @param s the ATN state
+	 * @return the expected symbols for each outgoing transition of {@code s}.
 	 */
 	@Nullable
 	public IntervalSet[] getDecisionLookahead(@Nullable ATNState s) {
@@ -81,12 +86,20 @@ public class LL1Analyzer {
 	}
 
 	/**
-	 * Get lookahead, using {@code ctx} if we reach end of rule. If {@code ctx}
+	 * Compute set of tokens that can follow {@code s} in the ATN in the
-	 * is {@code null} or {@link RuleContext#EMPTY EMPTY}, don't chase FOLLOW.
+	 * specified {@code ctx}.
-	 * If {@code ctx} is {@code null}, {@link Token#EPSILON EPSILON} is in set
+	 * <p/>
-	 * if we can reach end of rule. If {@code ctx} is
+	 * If {@code ctx} is {@code null} and the end of the rule containing
-	 * {@link RuleContext#EMPTY EMPTY}, {@link IntStream#EOF EOF} is in set if
+	 * {@code s} is reached, {@link Token#EPSILON} is added to the result set.
-	 * we can reach end of rule.
+	 * If {@code ctx} is not {@code null} and the end of the outermost rule is
+	 * reached, {@link Token#EOF} is added to the result set.
+	 *
+	 * @param s the ATN state
+	 * @param ctx the complete parser context, or {@code null} if the context
+	 * should be ignored
+	 *
+	 * @return The set of tokens that can follow {@code s} in the ATN in the
+	 * specified {@code ctx}.
 	 */
     @NotNull
    	public IntervalSet LOOK(@NotNull ATNState s, @Nullable RuleContext ctx) {
@@ -98,13 +111,34 @@ public class LL1Analyzer {
    		return r;
    	}
 
-    /** Compute set of tokens that can come next. If the {@code ctx} is {@link PredictionContext#EMPTY},
+	/**
-     *  then we don't go anywhere when we hit the end of the rule. We have
+	 * Compute set of tokens that can follow {@code s} in the ATN in the
-     *  the correct set.  If {@code ctx} is null, that means that we did not want
+	 * specified {@code ctx}.
-     *  any tokens following this rule--just the tokens that could be found within this
+	 * <p/>
-     *  rule. Add {@link Token#EPSILON} to the set indicating we reached the end of the ruled out having
+	 * If {@code ctx} is {@code null} and the end of the rule containing
-     *  to match a token.
+	 * {@code s} is reached, {@link Token#EPSILON} is added to the result set.
-     */
+	 * If {@code ctx} is not {@code null} and {@code addEOF} is {@code true} and
+	 * the end of the outermost rule is reached, {@link Token#EOF} is added to
+	 * the result set.
+	 *
+	 * @param s the ATN state.
+	 * @param ctx The outer context, or {@code null} if the outer context should
+	 * not be used.
+	 * @param look The result lookahead set.
+	 * @param lookBusy A set used for preventing epsilon closures in the ATN
+	 * from causing a stack overflow. Outside code should pass
+	 * {@code new HashSet<ATNConfig>} for this argument.
+	 * @param calledRuleStack A set used for preventing left recursion in the
+	 * ATN from causing a stack overflow. Outside code should pass
+	 * {@code new BitSet()} for this argument.
+	 * @param seeThruPreds {@code true} to true semantic predicates as
+	 * implicitly {@code true} and "see through them", otherwise {@code false}
+	 * to treat semantic predicates as opaque and add {@link #HIT_PRED} to the
+	 * result if one is encountered.
+	 * @param addEOF Add {@link Token#EOF} to the result if the end of the
+	 * outermost context is reached. This parameter has no effect if {@code ctx}
+	 * is {@code null}.
+	 */
     protected void _LOOK(@NotNull ATNState s, @Nullable PredictionContext ctx,
 						 @NotNull IntervalSet look,
                          @NotNull Set<ATNConfig> lookBusy,