Fixed javadoc errors

runtime/Java/src/org/antlr/v4/runtime/BufferedTokenStream.java

@@ -62,7 +62,7 @@ public class BufferedTokenStream implements TokenStream {
 	 * {@link #fetchedEOF} and {@link #p} instead of calling {@link #LA}.</li>
 	 * <li>{@link #fetch}: The check to prevent adding multiple EOF symbols into
 	 * {@link #tokens} is trivial with this field.</li>
-	 * <ul>
+	 * </ul>
 	 */
 	protected boolean fetchedEOF;
 

runtime/Java/src/org/antlr/v4/runtime/RuleContext.java

@@ -30,13 +30,15 @@
  *  SContext) and makes it the root of a parse tree, recorded by field
  *  Parser._ctx.
  *
+ *  <pre>
  *  public final SContext s() throws RecognitionException {
- *      SContext _localctx = new SContext(_ctx, getState()); <-- create new node
- *      enterRule(_localctx, 0, RULE_s);                     <-- push it
+ *      SContext _localctx = new SContext(_ctx, getState()); &lt;-- create new node
+ *      enterRule(_localctx, 0, RULE_s);                     &lt;-- push it
  *      ...
- *      exitRule();                                          <-- pop back to _localctx
+ *      exitRule();                                          &lt;-- pop back to _localctx
  *      return _localctx;
  *  }
+ *  </pre>
  *
  *  A subsequent rule invocation of r from the start rule s pushes a
  *  new context object for r whose parent points at s and use invoking
@@ -48,9 +50,11 @@
  *  symbol s then call r1, which calls r2, the  would look like
  *  this:
  *
- *     SContext[-1]   <- root node (bottom of the stack)
- *     R1Context[p]   <- p in rule s called r1
- *     R2Context[q]   <- q in rule r1 called r2
+ *  <pre>
+ *     SContext[-1]   &lt;- root node (bottom of the stack)
+ *     R1Context[p]   &lt;- p in rule s called r1
+ *     R2Context[q]   &lt;- q in rule r1 called r2
+ *  </pre>
  *
  *  So the top of the stack, _ctx, represents a call to the current
  *  rule and it holds the return address from another rule that invoke
@@ -65,6 +69,7 @@
  *
  *  @see ParserRuleContext
  */
+
 public class RuleContext implements RuleNode {
 	/** What context invoked this rule? */
 	public RuleContext parent;

runtime/Java/src/org/antlr/v4/runtime/Vocabulary.java

@@ -27,29 +27,14 @@ public interface Vocabulary {
 	 *
 	 * <p>The following table shows examples of lexer rules and the literal
 	 * names assigned to the corresponding token types.</p>
-	 *
-	 * <table>
-	 *  <tr>
-	 *   <th>Rule</th>
-	 *   <th>Literal Name</th>
-	 *   <th>Java String Literal</th>
-	 *  </tr>
-	 *  <tr>
-	 *   <td>{@code THIS : 'this';}</td>
-	 *   <td>{@code 'this'}</td>
-	 *   <td>{@code "'this'"}</td>
-	 *  </tr>
-	 *  <tr>
-	 *   <td>{@code SQUOTE : '\'';}</td>
-	 *   <td>{@code '\''}</td>
-	 *   <td>{@code "'\\''"}</td>
-	 *  </tr>
-	 *  <tr>
-	 *   <td>{@code ID : [A-Z]+;}</td>
-	 *   <td>n/a</td>
-	 *   <td>{@code null}</td>
-	 *  </tr>
-	 * </table>
+         * 
+         * <pre>
+         * Rule                 Literal Name    Java String Literal
+         * --------------------+---------------+-----------------------------
+         * {@code THIS   : 'this';}     {@code 'this'}          {@code "'this'"}
+         * {@code SQUOTE : '\'';}       {@code '\''}            {@code "'\\''"}
+         * {@code ID     : [A-Z]+;}     {@code n/a}             {@code null} 
+         * </pre>
 	 *
 	 * @param tokenType The token type.
 	 *
@@ -77,25 +62,14 @@ public interface Vocabulary {
 	 * <p>The following table shows examples of lexer rules and the literal
 	 * names assigned to the corresponding token types.</p>
 	 *
-	 * <table>
-	 *  <tr>
-	 *   <th>Rule</th>
-	 *   <th>Symbolic Name</th>
-	 *  </tr>
-	 *  <tr>
-	 *   <td>{@code THIS : 'this';}</td>
-	 *   <td>{@code THIS}</td>
-	 *  </tr>
-	 *  <tr>
-	 *   <td>{@code SQUOTE : '\'';}</td>
-	 *   <td>{@code SQUOTE}</td>
-	 *  </tr>
-	 *  <tr>
-	 *   <td>{@code ID : [A-Z]+;}</td>
-	 *   <td>{@code ID}</td>
-	 *  </tr>
-	 * </table>
-	 *
+         * <pre>
+         * Rule                 Symbolic Name
+         * --------------------+--------------------------
+	 * {@code THIS   : 'this';}     {@code THIS}
+	 * {@code SQUOTE : '\'';}       {@code SQUOTE}
+	 * {@code ID     : [A-Z]+;}     {@code ID} 
+	 * </pre>
+         *
 	 * @param tokenType The token type.
 	 *
 	 * @return The symbolic name associated with the specified token type, or

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

@@ -40,39 +40,39 @@
  *
  * <h3>Rule</h3>
  *
- * <embed src="images/Rule.svg" type="image/svg+xml"/>
+ * <img src="images/Rule.svg" alt="Basic Blocks: Rule." />
  *
  * <h3>Block of 1 or more alternatives</h3>
  *
- * <embed src="images/Block.svg" type="image/svg+xml"/>
+ * <img src="images/Block.svg" alt="Block of 1 or more alternatives." />
  *
  * <h2>Greedy Loops</h2>
  *
  * <h3>Greedy Closure: {@code (...)*}</h3>
  *
- * <embed src="images/ClosureGreedy.svg" type="image/svg+xml"/>
+ * <img src="images/ClosureGreedy.svg" alt="Greedy closure." />
  *
  * <h3>Greedy Positive Closure: {@code (...)+}</h3>
  *
- * <embed src="images/PositiveClosureGreedy.svg" type="image/svg+xml"/>
+ * <img src="images/PositiveClosureGreedy.svg" alt="Greedy positive closure." />
  *
  * <h3>Greedy Optional: {@code (...)?}</h3>
  *
- * <embed src="images/OptionalGreedy.svg" type="image/svg+xml"/>
+ * <img src="images/OptionalGreedy.svg" alt="Greedy optional." />
  *
  * <h2>Non-Greedy Loops</h2>
  *
  * <h3>Non-Greedy Closure: {@code (...)*?}</h3>
  *
- * <embed src="images/ClosureNonGreedy.svg" type="image/svg+xml"/>
+ * <img src="images/ClosureNonGreedy.svg" alt="Non-greedy closure." />
  *
  * <h3>Non-Greedy Positive Closure: {@code (...)+?}</h3>
  *
- * <embed src="images/PositiveClosureNonGreedy.svg" type="image/svg+xml"/>
+ * <img src="images/PositiveClosureNonGreedy.svg" alt="Non-greedy positive closure." />
  *
  * <h3>Non-Greedy Optional: {@code (...)??}</h3>
  *
- * <embed src="images/OptionalNonGreedy.svg" type="image/svg+xml"/>
+ * <img src="images/OptionalNonGreedy.svg" alt="Non-greedy optional." />
  */
 public abstract class ATNState {
 	public static final int INITIAL_NUM_TRANSITIONS = 4;

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

@@ -10,7 +10,8 @@
 
 public class ArrayPredictionContext extends PredictionContext {
 	/** Parent can be null only if full ctx mode and we make an array
-	 *  from {@link #EMPTY} and non-empty. We merge {@link #EMPTY} by using null parent and
+	 *  from {@link org.antlr.v4.runtime.ParserRuleContext#EMPTY} and non-empty. 
+	 *  We merge {@link org.antlr.v4.runtime.ParserRuleContext#EMPTY} by using null parent and
 	 *  returnState == {@link #EMPTY_RETURN_STATE}.
 	 */
 	public final PredictionContext[] parents;

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

@@ -11,9 +11,10 @@
  * and {@link SetTransition} appropriately based on the range of the input.
  *
  * Previously, we distinguished between atom and range transitions for
- * Unicode code points <= U+FFFF and those above. We used a set
- * transition for a Unicode code point > U+FFFF. Now that we can serialize
- * 32-bit int/chars in the ATN serialization, this is no longer necessary.
+ * Unicode code points &le; @code{U+FFFF} and those above. We used a set
+ * transition for a Unicode code point &gt; @code{U+FFFF}. Now that we can 
+ * serialize 32-bit int/chars in the ATN serialization, this is no longer 
+ * necessary.
  */
 public abstract class CodePointTransitions {
 	/** Return new {@link AtomTransition} */

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

@@ -1102,14 +1102,12 @@ bit of dipsIntoOuterContext (SUPPRESS_PRECEDENCE_FILTER).
 	 * The prediction context must be considered by this filter to address
 	 * situations like the following.
 	 * </p>
-	 * <code>
 	 * <pre>
 	 * grammar TA;
 	 * prog: statement* EOF;
 	 * statement: letterA | statement letterA 'b' ;
 	 * letterA: 'a';
 	 * </pre>
-	 * </code>
 	 * <p>
 	 * If the above grammar, the ATN state immediately before the token
 	 * reference {@code 'a'} in {@code letterA} is reachable from the left edge

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

@@ -28,7 +28,7 @@ public class PredicateEvalInfo extends DecisionEventInfo {
 	 * The alternative number for the decision which is guarded by the semantic
 	 * context {@link #semctx}. Note that other ATN
 	 * configurations may predict the same alternative which are guarded by
-	 * other semantic contexts and/or {@link SemanticContext#NONE}.
+	 * other semantic contexts.
 	 */
 	public final int predictedAlt;
 	/**

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

@@ -175,27 +175,35 @@ public static PredictionContext merge(
 	 * Merge two {@link SingletonPredictionContext} instances.
 	 *
 	 * <p>Stack tops equal, parents merge is same; return left graph.<br>
-	 * <embed src="images/SingletonMerge_SameRootSamePar.svg" type="image/svg+xml"/></p>
+	 * <img src="images/SingletonMerge_SameRootSamePar.svg" 
+	 *      alt="Merge two SingletonPredictionContext instance, case 1."/>
+	 * </p>
 	 *
 	 * <p>Same stack top, parents differ; merge parents giving array node, then
 	 * remainders of those graphs. A new root node is created to point to the
 	 * merged parents.<br>
-	 * <embed src="images/SingletonMerge_SameRootDiffPar.svg" type="image/svg+xml"/></p>
+	 * <img src="images/SingletonMerge_SameRootDiffPar.svg"
+	 *      alt="Merge two SingletonPredictionContext instance, case 2."/>
+	 * </p>  
 	 *
 	 * <p>Different stack tops pointing to same parent. Make array node for the
 	 * root where both element in the root point to the same (original)
 	 * parent.<br>
-	 * <embed src="images/SingletonMerge_DiffRootSamePar.svg" type="image/svg+xml"/></p>
+	 * <img src="images/SingletonMerge_DiffRootSamePar.svg"
+	 *      alt="Merge two SingletonPredictionContext instance, case 3."/>
+	 * </p>  
 	 *
 	 * <p>Different stack tops pointing to different parents. Make array node for
 	 * the root where each element points to the corresponding original
 	 * parent.<br>
-	 * <embed src="images/SingletonMerge_DiffRootDiffPar.svg" type="image/svg+xml"/></p>
+	 * <img src="images/SingletonMerge_DiffRootDiffPar.svg"
+	 *      alt="Merge two SingletonPredictionContext instance, case 4"/>
+	 * </p>  
 	 *
 	 * @param a the first {@link SingletonPredictionContext}
 	 * @param b the second {@link SingletonPredictionContext}
 	 * @param rootIsWildcard {@code true} if this is a local-context merge,
-	 * otherwise false to indicate a full-context merge
+	 * otherwise {@code false} to indicate a full-context merge
 	 * @param mergeCache
 	 */
 	public static PredictionContext mergeSingletons(
@@ -269,33 +277,42 @@ public static PredictionContext mergeSingletons(
 	 * {@link EmptyPredictionContext#Instance}. In the following diagrams, the symbol {@code $} is used
 	 * to represent {@link EmptyPredictionContext#Instance}.
 	 *
-	 * <h2>Local-Context Merges</h2>
+	 * <h4>Local-Context Merges</h4>
 	 *
-	 * <p>These local-context merge operations are used when {@code rootIsWildcard}
-	 * is true.</p>
+	 * <p>These local-context merge operations are used when {@code rootIsWildcard} is true.</p>
 	 *
 	 * <p>{@link EmptyPredictionContext#Instance} is superset of any graph; return {@link EmptyPredictionContext#Instance}.<br>
-	 * <embed src="images/LocalMerge_EmptyRoot.svg" type="image/svg+xml"/></p>
+	 * <img src="images/LocalMerge_EmptyRoot.svg"
+	 *      alt="Case where at least one of a or b is empty, subcase 1."/>
+	 * </p>  
 	 *
 	 * <p>{@link EmptyPredictionContext#Instance} and anything is {@code #EMPTY}, so merged parent is
 	 * {@code #EMPTY}; return left graph.<br>
-	 * <embed src="images/LocalMerge_EmptyParent.svg" type="image/svg+xml"/></p>
+	 * <img src="images/LocalMerge_EmptyParent.svg"
+	 *      alt="Case where at least one of a or b is empty, subcase 2."/>
+	 * </p>  
 	 *
 	 * <p>Special case of last merge if local context.<br>
-	 * <embed src="images/LocalMerge_DiffRoots.svg" type="image/svg+xml"/></p>
-	 *
-	 * <h2>Full-Context Merges</h2>
+	 * <img src="images/LocalMerge_DiffRoots.svg"
+	 *      alt="Case where at least one of a or b is empty, subcase 3."/>
+	 * </p>
 	 *
-	 * <p>These full-context merge operations are used when {@code rootIsWildcard}
-	 * is false.</p>
+	 * <h4>Full-Context Merges</h4>
 	 *
-	 * <p><embed src="images/FullMerge_EmptyRoots.svg" type="image/svg+xml"/></p>
+	 * <p>These full-context merge operations are used when {@code rootIsWildcard} is false.<br>
+	 * <img src="images/FullMerge_EmptyRoots.svg"
+	 *      alt="Full-context merge operations used when rootIsWildcard is false."/>
+	 * </p>
 	 *
-	 * <p>Must keep all contexts; {@link EmptyPredictionContext#Instance} in array is a special value (and
-	 * null parent).<br>
-	 * <embed src="images/FullMerge_EmptyRoot.svg" type="image/svg+xml"/></p>
+	 * <p>Must keep all contexts; {@link EmptyPredictionContext#Instance} in array is a special value (and null parent).<br>
+	 * <img src="images/FullMerge_EmptyRoot.svg"
+	 *      alt="Must keep all contexts, empty root." />
+	 * </p>
 	 *
-	 * <p><embed src="images/FullMerge_SameRoot.svg" type="image/svg+xml"/></p>
+	 * <p>
+	 * <img src="images/FullMerge_SameRoot.svg"
+	 *      alt="Must keep all contexts, same root." />
+	 * </p>
 	 *
 	 * @param a the first {@link SingletonPredictionContext}
 	 * @param b the second {@link SingletonPredictionContext}
@@ -334,20 +351,30 @@ public static PredictionContext mergeRoot(SingletonPredictionContext a,
 	 * Merge two {@link ArrayPredictionContext} instances.
 	 *
 	 * <p>Different tops, different parents.<br>
-	 * <embed src="images/ArrayMerge_DiffTopDiffPar.svg" type="image/svg+xml"/></p>
+	 * <img src="images/ArrayMerge_DiffTopDiffPar.svg"
+	 *      alt="Different tops, different parents." />
+	 * </p>
 	 *
 	 * <p>Shared top, same parents.<br>
-	 * <embed src="images/ArrayMerge_ShareTopSamePar.svg" type="image/svg+xml"/></p>
+	 * <img src="images/ArrayMerge_ShareTopSamePar.svg"
+	 *      alt="Shared top, same parents." />
+	 * </p>
 	 *
 	 * <p>Shared top, different parents.<br>
-	 * <embed src="images/ArrayMerge_ShareTopDiffPar.svg" type="image/svg+xml"/></p>
+	 * <img src="images/ArrayMerge_ShareTopDiffPar.svg"
+	 *      alt="Shared top, different parents." />
+	 * </p>
 	 *
 	 * <p>Shared top, all shared parents.<br>
-	 * <embed src="images/ArrayMerge_ShareTopSharePar.svg" type="image/svg+xml"/></p>
+	 * <img src="images/ArrayMerge_ShareTopSharePar.svg"
+	 *      alt="Shared top, all shared parents." />
+	 * </p>
 	 *
 	 * <p>Equal tops, merge parents and reduce top to
 	 * {@link SingletonPredictionContext}.<br>
-	 * <embed src="images/ArrayMerge_EqualTop.svg" type="image/svg+xml"/></p>
+	 * <img src="images/ArrayMerge_EqualTop.svg"
+	 *      alt="Equal tops, merge parents and reduce top to SingletonPredictionContext." />
+	 * </p>
 	 */
 	public static PredictionContext mergeArrays(
 		ArrayPredictionContext a,

runtime/Java/src/org/antlr/v4/runtime/misc/InterpreterDataReader.java

@@ -30,8 +30,13 @@ public static class InterpreterData {
 	};
 
 	/**
-	 * The structure of the data file is very simple. Everything is line based with empty lines
-	 * separating the different parts. For lexers the layout is:
+	 * Parse the file given by {@code fileName}.
+	 *
+	 * The structure of the data file is very simple. 
+	 * Everything is line based with empty lines separating the different parts. 
+	 * For lexers the layout is:
+	 *
+	 * <pre>
 	 * token literal names:
 	 * ...
 	 *
@@ -48,9 +53,13 @@ public static class InterpreterData {
 	 * ...
 	 *
 	 * atn:
-	 * <a single line with comma separated int values> enclosed in a pair of squared brackets.
+	 * a single line with comma separated int values enclosed in a pair of square brackets.
+	 * </pre>
 	 *
 	 * Data for a parser does not contain channel and mode names.
+	 *
+	 * @param fileName File to read with a {@link java.io.FileReader}, so we assume that the
+	 *                 default character encoding and the default byte-buffer size are appropriate.
 	 */
 	public static InterpreterData parseFile(String fileName) {
 		InterpreterData result = new InterpreterData();

runtime/Java/src/org/antlr/v4/runtime/tree/ParseTreeListener.java

@@ -11,8 +11,10 @@
 /** This interface describes the minimal core of methods triggered
  *  by {@link ParseTreeWalker}. E.g.,
  *
+ *  <pre>
  *  	ParseTreeWalker walker = new ParseTreeWalker();
- *		walker.walk(myParseTreeListener, myParseTree); <-- triggers events in your listener
+ *		walker.walk(myParseTreeListener, myParseTree); &lt;-- triggers events in your listener
+ *  </pre>
  *
  *  If you want to trigger events in multiple listeners during a single
  *  tree walk, you can use the ParseTreeDispatcher object available at