From be6a7ca77be3de342656ec381aaa02b89da252d4 Mon Sep 17 00:00:00 2001
From: Baratali Izmailov <barataliba@gmail.com>
Date: Mon, 24 Nov 2014 21:12:48 +0300
Subject: [PATCH] Create ParseErrorMessage if error message is null. Added
 comments for a few methods.

---
 .../checks/javadoc/AbstractJavadocCheck.java  | 37 ++++++++++++++++++-
 .../checks/javadoc/messages.properties        |  2 +
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.java
index ade34d7e2..228194ea9 100755
--- a/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.java
+++ b/src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/AbstractJavadocCheck.java
@@ -54,6 +54,17 @@ import com.puppycrawl.tools.checkstyle.grammars.javadoc.JavadocParser;
  */
 public abstract class AbstractJavadocCheck extends Check
 {
+    /**
+     * Error message key for common javadoc errors.
+     */
+    private static final String PARSE_ERROR_MESSAGE_KEY = "javadoc.parse.error";
+
+    /**
+     * Unrecognized error from antlr parser
+     */
+    private static final String UNRECOGNIZED_ANTLR_ERROR_MESSAGE_KEY =
+            "javadoc.unrecognized.antlr.error";
+
     /**
      * key is "line:column"
      * value is DetailNode tree
@@ -115,24 +126,40 @@ public abstract class AbstractJavadocCheck extends Check
     {
     }
 
+    /**
+     * Defined final to not allow JavadocChecks to change default tokens.
+     * @return default tokens
+     */
     @Override
     public final int[] getDefaultTokens()
     {
         return new int[] {TokenTypes.BLOCK_COMMENT_BEGIN };
     }
 
+    /**
+     * Defined final to not allow JavadocChecks to change acceptable tokens.
+     * @return acceptable tokens
+     */
     @Override
     public final int[] getAcceptableTokens()
     {
         return super.getAcceptableTokens();
     }
 
+    /**
+     * Defined final to not allow JavadocChecks to change required tokens.
+     * @return required tokens
+     */
     @Override
     public final int[] getRequiredTokens()
     {
         return super.getRequiredTokens();
     }
 
+    /**
+     * Defined final because all JavadocChecks require comment nodes.
+     * @return true
+     */
     @Override
     public final boolean isCommentNodesRequired()
     {
@@ -142,6 +169,7 @@ public abstract class AbstractJavadocCheck extends Check
     @Override
     public final void beginTree(DetailAST aRootAST)
     {
+        TREE_CACHE.clear();
     }
 
     @Override
@@ -217,7 +245,7 @@ public abstract class AbstractJavadocCheck extends Check
         catch (IOException e) {
             // Antlr can not initiate its ANTLRInputStream
             parseErrorMessage = new ParseErrorMessage(aJavadocCommentAst.getLineNo(),
-                    "javadoc.parse.error",
+                    PARSE_ERROR_MESSAGE_KEY,
                     aJavadocCommentAst.getColumnNo(), e.getMessage());
         }
         catch (ParseCancellationException e) {
@@ -225,6 +253,13 @@ public abstract class AbstractJavadocCheck extends Check
             // and parser throws this runtime exception to stop parsing.
             // Just stop processing current Javadoc comment.
             parseErrorMessage = mErrorListener.getErrorMessage();
+
+            // There are cases when antlr error listener does not handle syntax error
+            if (parseErrorMessage == null) {
+                parseErrorMessage = new ParseErrorMessage(aJavadocCommentAst.getLineNo(),
+                        UNRECOGNIZED_ANTLR_ERROR_MESSAGE_KEY,
+                        aJavadocCommentAst.getColumnNo(), e.getMessage());
+            }
         }
 
         if (parseErrorMessage == null) {
diff --git a/src/main/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/messages.properties b/src/main/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/messages.properties
index eea7a35da..1976b3a03 100644
--- a/src/main/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/messages.properties
+++ b/src/main/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/messages.properties
@@ -1,3 +1,5 @@
+javadoc.parse.error=Javadoc comment at column {0} has parse error. Details: {1}
+javadoc.unrecognized.antlr.error=Javadoc comment at column {0} has parse error. Unrecognized error from ANTLR parser: {1}
 javadoc.parse.token.error=Javadoc comment at column {0} has parse error. Details: {1}
 javadoc.parse.rule.error=Javadoc comment at column {0} has parse error. Details: {1} while parsing {2}
 javadoc.missed.html.close=Javadoc comment at column {0} has parse error. Missed HTML close tag ''{1}''. Sometimes it means that close tag missed for one of previous tags.