From 4507c1a27066a6e7abf7239586277d064f786dd5 Mon Sep 17 00:00:00 2001 From: Sam Harwell Date: Sat, 18 Jan 2014 20:59:59 -0600 Subject: [PATCH] Fix many errors reported by -Xdoclint --- .../org/antlr/mojo/antlr4/Antlr4Mojo.java | 6 +- .../antlr/v4/runtime/ANTLRErrorListener.java | 48 ++-- .../antlr/v4/runtime/ANTLRErrorStrategy.java | 22 +- .../antlr/v4/runtime/ANTLRInputStream.java | 4 +- .../antlr/v4/runtime/BailErrorStrategy.java | 4 +- .../antlr/v4/runtime/BufferedTokenStream.java | 12 +- .../src/org/antlr/v4/runtime/CommonToken.java | 2 +- .../v4/runtime/DefaultErrorStrategy.java | 140 +++++------ .../src/org/antlr/v4/runtime/IntStream.java | 52 ++--- .../org/antlr/v4/runtime/ListTokenSource.java | 20 +- .../Java/src/org/antlr/v4/runtime/Parser.java | 50 ++-- .../v4/runtime/RecognitionException.java | 22 +- .../src/org/antlr/v4/runtime/Recognizer.java | 14 +- .../src/org/antlr/v4/runtime/TokenSource.java | 6 +- .../src/org/antlr/v4/runtime/TokenStream.java | 34 +-- .../antlr/v4/runtime/TokenStreamRewriter.java | 6 +- .../v4/runtime/UnbufferedCharStream.java | 16 +- .../v4/runtime/UnbufferedTokenStream.java | 22 +- .../src/org/antlr/v4/runtime/atn/ATN.java | 6 +- .../org/antlr/v4/runtime/atn/ATNConfig.java | 2 +- .../antlr/v4/runtime/atn/ATNConfigSet.java | 6 +- .../antlr/v4/runtime/atn/ATNSerializer.java | 2 +- .../antlr/v4/runtime/atn/ATNSimulator.java | 12 +- .../org/antlr/v4/runtime/atn/LL1Analyzer.java | 18 +- .../v4/runtime/atn/LexerATNSimulator.java | 12 +- .../org/antlr/v4/runtime/atn/LexerAction.java | 12 +- .../v4/runtime/atn/LexerActionExecutor.java | 30 +-- .../v4/runtime/atn/LexerChannelAction.java | 6 +- .../v4/runtime/atn/LexerCustomAction.java | 18 +- .../runtime/atn/LexerIndexedCustomAction.java | 18 +- .../antlr/v4/runtime/atn/LexerModeAction.java | 6 +- .../antlr/v4/runtime/atn/LexerMoreAction.java | 10 +- .../v4/runtime/atn/LexerPopModeAction.java | 10 +- .../v4/runtime/atn/LexerPushModeAction.java | 6 +- .../antlr/v4/runtime/atn/LexerSkipAction.java | 10 +- .../antlr/v4/runtime/atn/LexerTypeAction.java | 6 +- .../v4/runtime/atn/ParserATNSimulator.java | 26 +-- .../v4/runtime/atn/PredictionContext.java | 110 ++++----- .../antlr/v4/runtime/atn/PredictionMode.java | 220 ++++++------------ .../antlr/v4/runtime/atn/SemanticContext.java | 12 +- .../v4/runtime/atn/StarLoopEntryState.java | 6 +- .../org/antlr/v4/runtime/atn/Transition.java | 12 +- .../src/org/antlr/v4/runtime/dfa/DFA.java | 2 +- .../org/antlr/v4/runtime/dfa/DFAState.java | 36 +-- .../antlr/v4/runtime/misc/IntegerList.java | 6 +- .../org/antlr/v4/runtime/misc/Interval.java | 2 +- .../antlr/v4/runtime/misc/IntervalSet.java | 6 +- .../misc/ObjectEqualityComparator.java | 12 +- .../src/org/antlr/v4/runtime/misc/Utils.java | 4 +- .../tree/AbstractParseTreeVisitor.java | 46 ++-- .../org/antlr/v4/runtime/tree/ParseTree.java | 4 +- .../org/antlr/v4/runtime/tree/SyntaxTree.java | 4 +- .../v4/runtime/tree/gui/BasicFontMetrics.java | 8 +- .../antlr/v4/runtime/tree/pattern/Chunk.java | 6 +- .../runtime/tree/pattern/ParseTreeMatch.java | 24 +- .../tree/pattern/ParseTreePatternMatcher.java | 58 ++--- .../v4/runtime/tree/pattern/RuleTagToken.java | 50 ++-- .../v4/runtime/tree/pattern/TextChunk.java | 6 +- .../runtime/tree/pattern/TokenTagToken.java | 12 +- 59 files changed, 615 insertions(+), 727 deletions(-) diff --git a/antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java b/antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java index c77b0be1c..40c302f43 100644 --- a/antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java +++ b/antlr4-maven-plugin/src/main/java/org/antlr/mojo/antlr4/Antlr4Mojo.java @@ -212,9 +212,9 @@ public class Antlr4Mojo extends AbstractMojo { * The main entry point for this Mojo, it is responsible for converting * ANTLR 4.x grammars into the target language specified by the grammar. * - * @throws MojoExecutionException if a configuration or grammar error causes + * @exception MojoExecutionException if a configuration or grammar error causes * the code generation process to fail - * @throws MojoFailureException if an instance of the ANTLR 4 {@link Tool} + * @exception MojoFailureException if an instance of the ANTLR 4 {@link Tool} * cannot be created */ @Override @@ -353,7 +353,7 @@ public class Antlr4Mojo extends AbstractMojo { /** * * @param sourceDirectory - * @throws InclusionScanException + * @exception InclusionScanException */ @NotNull private List> processGrammarFiles(List args, File sourceDirectory) throws InclusionScanException { diff --git a/runtime/Java/src/org/antlr/v4/runtime/ANTLRErrorListener.java b/runtime/Java/src/org/antlr/v4/runtime/ANTLRErrorListener.java index d78d44657..a1ef82b0e 100644 --- a/runtime/Java/src/org/antlr/v4/runtime/ANTLRErrorListener.java +++ b/runtime/Java/src/org/antlr/v4/runtime/ANTLRErrorListener.java @@ -47,11 +47,11 @@ public interface ANTLRErrorListener { * specifies how to recover from syntax errors and how to compute error * messages. This listener's job is simply to emit a computed message, * though it has enough information to create its own message in many cases. - *

- * The {@link RecognitionException} is non-null for all syntax errors except + * + *

The {@link RecognitionException} is non-null for all syntax errors except * when we discover mismatched token errors that we can recover from * in-line, without returning from the surrounding rule (via the single - * token insertion and deletion mechanism). + * token insertion and deletion mechanism).

* * @param recognizer * What parser got the error. From this @@ -84,19 +84,19 @@ public interface ANTLRErrorListener { /** * This method is called by the parser when a full-context prediction * results in an ambiguity. - *

- * When {@code exact} is {@code true}, all of the alternatives in + * + *

When {@code exact} is {@code true}, all of the alternatives in * {@code ambigAlts} are viable, i.e. this is reporting an exact ambiguity. * When {@code exact} is {@code false}, at least two of the * alternatives in {@code ambigAlts} are viable for the current input, but * the prediction algorithm terminated as soon as it determined that at - * least the minimum alternative in {@code ambigAlts} is viable. - *

- * When the {@link PredictionMode#LL_EXACT_AMBIG_DETECTION} prediction mode + * least the minimum alternative in {@code ambigAlts} is viable.

+ * + *

When the {@link PredictionMode#LL_EXACT_AMBIG_DETECTION} prediction mode * is used, the parser is required to identify exact ambiguities so - * {@code exact} will always be {@code true}. - *

- * This method is not used by lexers. + * {@code exact} will always be {@code true}.

+ * + *

This method is not used by lexers.

* * @param recognizer the parser instance * @param dfa the DFA for the current decision @@ -120,13 +120,13 @@ public interface ANTLRErrorListener { /** * This method is called when an SLL conflict occurs and the parser is about * to use the full context information to make an LL decision. - *

- * If one or more configurations in {@code configs} contains a semantic + * + *

If one or more configurations in {@code configs} contains a semantic * predicate, the predicates are evaluated before this method is called. The * subset of alternatives which are still viable after predicates are - * evaluated is reported in {@code conflictingAlts}. - *

- * This method is not used by lexers. + * evaluated is reported in {@code conflictingAlts}.

+ * + *

This method is not used by lexers.

* * @param recognizer the parser instance * @param dfa the DFA for the current decision @@ -148,21 +148,21 @@ public interface ANTLRErrorListener { /** * This method is called by the parser when a full-context prediction has a * unique result. - *

- * For prediction implementations that only evaluate full-context + * + *

For prediction implementations that only evaluate full-context * predictions when an SLL conflict is found (including the default * {@link ParserATNSimulator} implementation), this method reports cases * where SLL conflicts were resolved to unique full-context predictions, * i.e. the decision was context-sensitive. This report does not necessarily * indicate a problem, and it may appear even in completely unambiguous - * grammars. - *

- * {@code configs} may have more than one represented alternative if the + * grammars.

+ * + *

{@code configs} may have more than one represented alternative if the * full-context prediction algorithm does not evaluate predicates before * beginning the full-context prediction. In all cases, the final prediction - * is passed as the {@code prediction} argument. - *

- * This method is not used by lexers. + * is passed as the {@code prediction} argument.

+ * + *

This method is not used by lexers.

* * @param recognizer the parser instance * @param dfa the DFA for the current decision diff --git a/runtime/Java/src/org/antlr/v4/runtime/ANTLRErrorStrategy.java b/runtime/Java/src/org/antlr/v4/runtime/ANTLRErrorStrategy.java index 5907e6632..ff1ebf02f 100644 --- a/runtime/Java/src/org/antlr/v4/runtime/ANTLRErrorStrategy.java +++ b/runtime/Java/src/org/antlr/v4/runtime/ANTLRErrorStrategy.java @@ -46,8 +46,8 @@ import org.antlr.v4.runtime.misc.NotNull; * * Implementations of this interface report syntax errors by calling * {@link Parser#notifyErrorListeners}. - *

- * TODO: what to do about lexers + * + *

TODO: what to do about lexers

*/ public interface ANTLRErrorStrategy { /** @@ -62,10 +62,10 @@ public interface ANTLRErrorStrategy { * strategy successfully recovers from the match failure, this method * returns the {@link Token} instance which should be treated as the * successful result of the match. - *

- * Note that the calling code will not report an error if this method + * + *

Note that the calling code will not report an error if this method * returns successfully. The error strategy implementation is responsible - * for calling {@link Parser#notifyErrorListeners} as appropriate. + * for calling {@link Parser#notifyErrorListeners} as appropriate.

* * @param recognizer the parser instance * @throws RecognitionException if the error strategy was not able to @@ -95,13 +95,13 @@ public interface ANTLRErrorStrategy { * This method provides the error handler with an opportunity to handle * syntactic or semantic errors in the input stream before they result in a * {@link RecognitionException}. - *

- * The generated code currently contains calls to {@link #sync} after + * + *

The generated code currently contains calls to {@link #sync} after * entering the decision state of a closure block ({@code (...)*} or - * {@code (...)+}). - *

- * For an implementation based on Jim Idle's "magic sync" mechanism, see - * {@link DefaultErrorStrategy#sync}. + * {@code (...)+}).

+ * + *

For an implementation based on Jim Idle's "magic sync" mechanism, see + * {@link DefaultErrorStrategy#sync}.

* * @see DefaultErrorStrategy#sync * diff --git a/runtime/Java/src/org/antlr/v4/runtime/ANTLRInputStream.java b/runtime/Java/src/org/antlr/v4/runtime/ANTLRInputStream.java index 3298e2794..d120b1c96 100644 --- a/runtime/Java/src/org/antlr/v4/runtime/ANTLRInputStream.java +++ b/runtime/Java/src/org/antlr/v4/runtime/ANTLRInputStream.java @@ -41,8 +41,8 @@ import java.util.Arrays; * Vacuum all input from a {@link Reader}/{@link InputStream} and then treat it * like a {@code char[]} buffer. Can also pass in a {@link String} or * {@code char[]} to use. - *

- * If you need encoding, pass in stream/reader with correct encoding. + * + *

If you need encoding, pass in stream/reader with correct encoding.

*/ public class ANTLRInputStream implements CharStream { public static final int READ_BUFFER_SIZE = 1024; diff --git a/runtime/Java/src/org/antlr/v4/runtime/BailErrorStrategy.java b/runtime/Java/src/org/antlr/v4/runtime/BailErrorStrategy.java index f13bd194a..cdf8379bc 100644 --- a/runtime/Java/src/org/antlr/v4/runtime/BailErrorStrategy.java +++ b/runtime/Java/src/org/antlr/v4/runtime/BailErrorStrategy.java @@ -33,8 +33,8 @@ package org.antlr.v4.runtime; import org.antlr.v4.runtime.misc.ParseCancellationException; /** Bail out of parser at first syntax error. Do this to use it: - *

- * {@code myparser.setErrorHandler(new BailErrorStrategy());} + * + *

{@code myparser.setErrorHandler(new BailErrorStrategy());}

*/ public class BailErrorStrategy extends DefaultErrorStrategy { /** Instead of recovering from exception {@code e}, re-throw it wrapped diff --git a/runtime/Java/src/org/antlr/v4/runtime/BufferedTokenStream.java b/runtime/Java/src/org/antlr/v4/runtime/BufferedTokenStream.java index f0848f914..dba0acfd9 100644 --- a/runtime/Java/src/org/antlr/v4/runtime/BufferedTokenStream.java +++ b/runtime/Java/src/org/antlr/v4/runtime/BufferedTokenStream.java @@ -45,11 +45,11 @@ import java.util.Set; * because it has to constantly flip back and forth between inside/output * templates. E.g., {@code }>} has to parse names as part of an * expression but {@code "hi, "} as a nested template. - *

- * You can't use this stream if you pass whitespace or other off-channel tokens + * + *

You can't use this stream if you pass whitespace or other off-channel tokens * to the parser. The stream can't ignore off-channel tokens. * ({@link UnbufferedTokenStream} is the same way.) Use - * {@link CommonTokenStream}. + * {@link CommonTokenStream}.

*/ public class BufferedTokenStream implements TokenStream { @NotNull @@ -222,9 +222,9 @@ public class BufferedTokenStream implements TokenStream { * operation. The default implementation simply returns {@code i}. If an * exception is thrown in this method, the current stream index should not be * changed. - *

- * For example, {@link CommonTokenStream} overrides this method to ensure that - * the seek target is always an on-channel token. + * + *

For example, {@link CommonTokenStream} overrides this method to ensure that + * the seek target is always an on-channel token.

* * @param i The target token index. * @return The adjusted target token index. diff --git a/runtime/Java/src/org/antlr/v4/runtime/CommonToken.java b/runtime/Java/src/org/antlr/v4/runtime/CommonToken.java index 66460b666..e316b8155 100644 --- a/runtime/Java/src/org/antlr/v4/runtime/CommonToken.java +++ b/runtime/Java/src/org/antlr/v4/runtime/CommonToken.java @@ -52,7 +52,7 @@ public class CommonToken implements WritableToken, Serializable { // TODO: can store these in map in token stream rather than as field here protected String text; - /** What token number is this from 0..n-1 tokens; < 0 implies invalid index */ + /** What token number is this from 0..n-1 tokens; < 0 implies invalid index */ protected int index = -1; /** The char position into the input buffer where this token starts */ diff --git a/runtime/Java/src/org/antlr/v4/runtime/DefaultErrorStrategy.java b/runtime/Java/src/org/antlr/v4/runtime/DefaultErrorStrategy.java index 91bb1f661..79438b485 100644 --- a/runtime/Java/src/org/antlr/v4/runtime/DefaultErrorStrategy.java +++ b/runtime/Java/src/org/antlr/v4/runtime/DefaultErrorStrategy.java @@ -62,9 +62,9 @@ public class DefaultErrorStrategy implements ANTLRErrorStrategy { /** * {@inheritDoc} - *

- * The default implementation simply calls {@link #endErrorCondition} to - * ensure that the handler is not in error recovery mode. + * + *

The default implementation simply calls {@link #endErrorCondition} to + * ensure that the handler is not in error recovery mode.

*/ @Override public void reset(Parser recognizer) { @@ -103,8 +103,8 @@ public class DefaultErrorStrategy implements ANTLRErrorStrategy { /** * {@inheritDoc} - *

- * The default implementation simply calls {@link #endErrorCondition}. + * + *

The default implementation simply calls {@link #endErrorCondition}.

*/ @Override public void reportMatch(Parser recognizer) { @@ -113,11 +113,11 @@ public class DefaultErrorStrategy implements ANTLRErrorStrategy { /** * {@inheritDoc} - *

- * The default implementation returns immediately if the handler is already + * + *

The default implementation returns immediately if the handler is already * in error recovery mode. Otherwise, it calls {@link #beginErrorCondition} * and dispatches the reporting task based on the runtime type of {@code e} - * according to the following table. + * according to the following table.

* *