diff --git a/tool/src/org/antlr/v4/automata/ParserATNFactory.java b/tool/src/org/antlr/v4/automata/ParserATNFactory.java
index 9244088f6..c880090d3 100644
--- a/tool/src/org/antlr/v4/automata/ParserATNFactory.java
+++ b/tool/src/org/antlr/v4/automata/ParserATNFactory.java
@@ -159,7 +159,7 @@ public class ParserATNFactory implements ATNFactory {
 		return h;
 	}
 
-	/** From label A build Graph o-A->o */
+	/** From label {@code A} build graph {@code o-A->o}. */
 	@Override
 	public Handle tokenRef(TerminalAST node) {
 		ATNState left = newState(node);
@@ -170,9 +170,9 @@ public class ParserATNFactory implements ATNFactory {
 		return new Handle(left, right);
 	}
 
-	/** From set build single edge graph o->o-set->o.  To conform to
+	/** From set build single edge graph {@code o->o-set->o}.  To conform to
      *  what an alt block looks like, must have extra state on left.
-	 *  This handles ~A also, converted to ~{A} set.
+	 *  This also handles {@code ~A}, converted to {@code ~{A}} set.
      */
 	@Override
 	public Handle set(GrammarAST associatedAST, List<GrammarAST> terminals, boolean invert) {
@@ -193,7 +193,7 @@ public class ParserATNFactory implements ATNFactory {
 		return new Handle(left, right);
 	}
 
-	/** Not valid for non-lexers */
+	/** Not valid for non-lexers. */
 	@Override
 	public Handle range(GrammarAST a, GrammarAST b) {
 		throw new UnsupportedOperationException();
@@ -216,18 +216,22 @@ public class ParserATNFactory implements ATNFactory {
 		return tokenRef(stringLiteralAST);
 	}
 
-	/** [Aa] char sets not allowed in parser */
+	/** {@code [Aa]} char sets not allowed in parser */
 	@Override
 	public Handle charSetLiteral(GrammarAST charSetAST) {
 		return null;
 	}
 
-	/** For reference to rule r, build
+	/**
+	 * For reference to rule {@code r}, build
 	 *
+	 * <pre>
 	 *  o->(r)  o
+	 * </pre>
 	 *
-	 *  where (r) is the start of rule r and the trailing o is not linked
-	 *  to from rule ref state directly (uses followState).
+	 * where {@code (r)} is the start of rule {@code r} and the trailing
+	 * {@code o} is not linked to from rule ref state directly (uses
+	 * {@link RuleTransition#followState}).
 	 */
 	@Override
 	public Handle ruleRef(GrammarAST node) {
@@ -258,7 +262,7 @@ public class ParserATNFactory implements ATNFactory {
 		epsilon(stop, right);
 	}
 
-	/** From an empty alternative build  o-e->o */
+	/** From an empty alternative build {@code o-e->o}. */
 	@Override
 	public Handle epsilon(GrammarAST node) {
 		ATNState left = newState(node);
@@ -269,8 +273,8 @@ public class ParserATNFactory implements ATNFactory {
 	}
 
 	/** Build what amounts to an epsilon transition with a semantic
-	 *  predicate action.  The pred is a pointer into the AST of
-	 *  the SEMPRED token.
+	 *  predicate action.  The {@code pred} is a pointer into the AST of
+	 *  the {@link ANTLRParser#SEMPRED} token.
 	 */
 	@Override
 	public Handle sempred(PredAST pred) {
@@ -286,7 +290,7 @@ public class ParserATNFactory implements ATNFactory {
 
 	/** Build what amounts to an epsilon transition with an action.
 	 *  The action goes into ATN though it is ignored during prediction
-	 *  if actionIndex &lt; 0.  Only forced are executed during prediction.
+	 *  if {@link ActionTransition#actionIndex actionIndex}{@code <0}.
 	 */
 	@Override
 	public Handle action(ActionAST action) {
@@ -304,26 +308,29 @@ public class ParserATNFactory implements ATNFactory {
 		return null;
 	}
 
-	/** From A|B|..|Z alternative block build
-     *
-     *  o->o-A->o->o (last ATNState is BlockEndState pointed to by all alts)
-     *  |          ^
-     *  |->o-B->o--|
-     *  |          |
-     *  ...        |
-     *  |          |
-     *  |->o-Z->o--|
-     *
-     *  So start node points at every alternative with epsilon transition
-	 *  and every alt right side points at a block end ATNState.
+	/**
+	 * From {@code A|B|..|Z} alternative block build
 	 *
-	 *  Special case: only one alternative: don't make a block with alt
-	 *  begin/end.
+	 * <pre>
+	 *  o->o-A->o->o (last ATNState is BlockEndState pointed to by all alts)
+	 *  |          ^
+	 *  |->o-B->o--|
+	 *  |          |
+	 *  ...        |
+	 *  |          |
+	 *  |->o-Z->o--|
+	 * </pre>
 	 *
-	 *  Special case: if just a list of tokens/chars/sets, then collapse
-	 *  to a single edged o-set->o graph.
-	 *
-	 *  TODO: Set alt number (1..n) in the states?
+	 * So start node points at every alternative with epsilon transition and
+	 * every alt right side points at a block end ATNState.
+	 * <p/>
+	 * Special case: only one alternative: don't make a block with alt
+	 * begin/end.
+	 * <p/>
+	 * Special case: if just a list of tokens/chars/sets, then collapse to a
+	 * single edged o-set->o graph.
+	 * <p/>
+	 * TODO: Set alt number (1..n) in the states?
 	 */
 	@Override
 	public Handle block(BlockAST blkAST, GrammarAST ebnfRoot, List<Handle> alts) {
@@ -413,13 +420,17 @@ public class ParserATNFactory implements ATNFactory {
 		return new Handle(first.left, last.right);
 	}
 
-	/** From (A)? build either:
+	/**
+	 * From {@code (A)?} build either:
 	 *
+	 * <pre>
 	 *  o--A->o
 	 *  |     ^
 	 *  o---->|
+	 * </pre>
 	 *
-	 *  or, if A is a block, just add an empty alt to the end of the block
+	 * or, if {@code A} is a block, just add an empty alt to the end of the
+	 * block
 	 */
 	@NotNull
 	@Override
@@ -439,14 +450,17 @@ public class ParserATNFactory implements ATNFactory {
 		return blk;
 	}
 
-	/** From (blk)+ build
+	/**
+	 * From {@code (blk)+} build
 	 *
+	 * <pre>
 	 *   |---------|
 	 *   v         |
 	 *  [o-blk-o]->o->o
+	 * </pre>
 	 *
-	 *  We add a decision for loop back node to the existing one at
-	 *  blk start.
+	 * We add a decision for loop back node to the existing one at {@code blk}
+	 * start.
 	 */
 	@NotNull
 	@Override
@@ -482,17 +496,20 @@ public class ParserATNFactory implements ATNFactory {
 		return new Handle(blkStart, end);
 	}
 
-	/** From (blk)* build ( blk+ )? with *two* decisions, one for entry
-	 *  and one for choosing alts of blk.
+	/**
+	 * From {@code (blk)*} build {@code ( blk+ )?} with *two* decisions, one for
+	 * entry and one for choosing alts of {@code blk}.
 	 *
+	 * <pre>
 	 *   |-------------|
 	 *   v             |
 	 *   o--[o-blk-o]->o  o
 	 *   |                ^
 	 *   -----------------|
+	 * </pre>
 	 *
-	 *  Note that the optional bypass must jump outside the loop as (A|B)* is
-	 *  not the same thing as (A|B|)+.
+	 * Note that the optional bypass must jump outside the loop as
+	 * {@code (A|B)*} is not the same thing as {@code (A|B|)+}.
 	 */
 	@NotNull
 	@Override
@@ -529,7 +546,7 @@ public class ParserATNFactory implements ATNFactory {
 		return new Handle(entry, end);
 	}
 
-	/** Build an atom with all possible values in its label */
+	/** Build an atom with all possible values in its label. */
 	@NotNull
 	@Override
 	public Handle wildcard(GrammarAST node) {
@@ -573,7 +590,7 @@ public class ParserATNFactory implements ATNFactory {
         }
     }
 
-	/** add an EOF transition to any rule end ATNState that points to nothing
+	/** Add an EOF transition to any rule end ATNState that points to nothing
      *  (i.e., for all those rules not invoked by another rule).  These
      *  are start symbols then.
 	 *
@@ -641,7 +658,9 @@ public class ParserATNFactory implements ATNFactory {
 		return false;
 	}
 
-	// (BLOCK (ALT .)) or (BLOCK (ALT 'a') (ALT .))
+	/**
+	 * {@code (BLOCK (ALT .))} or {@code (BLOCK (ALT 'a') (ALT .))}.
+	 */
 	public static boolean blockHasWildcardAlt(@NotNull GrammarAST block) {
 		for (Object alt : block.getChildren()) {
 			if ( !(alt instanceof AltAST) ) continue;