Issue checkstyle#3908: SummaryJavadoc need special processing of inhe…

…ritDoc tag

src/main/java/com/puppycrawl/tools/checkstyle/checks/javadoc/SummaryJavadocCheck.java

@@ -19,6 +19,9 @@
 
 package com.puppycrawl.tools.checkstyle.checks.javadoc;
 
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.Set;
 import java.util.regex.Pattern;
 
 import com.google.common.base.CharMatcher;
@@ -82,6 +85,14 @@ public class SummaryJavadocCheck extends AbstractJavadocCheck {
     /** Period literal. */
     private static final String PERIOD = ".";
 
+    /**
+     * Stores allowed values in document for inherit doc literal.
+     */
+    private static final Set<Integer> SKIP_TOKENS = new HashSet<>(
+        Arrays.asList(JavadocTokenTypes.NEWLINE,
+                       JavadocTokenTypes.LEADING_ASTERISK,
+                       JavadocTokenTypes.EOF)
+    );
     /**
      * Regular expression for forbidden summary fragments.
      */
@@ -135,7 +146,7 @@ public void visitJavadocToken(DetailNode ast) {
         String firstSentence = getFirstSentence(ast);
         final int endOfSentence = firstSentence.lastIndexOf(period);
         if (endOfSentence == -1) {
-            if (!firstSentence.trim().startsWith("{@inheritDoc}")) {
+            if (!isOnlyInheritDoc(ast)) {
                 log(ast.getLineNumber(), MSG_SUMMARY_FIRST_SENTENCE);
             }
         }
@@ -147,6 +158,38 @@ public void visitJavadocToken(DetailNode ast) {
         }
     }
 
+    /**
+     * Finds if inheritDoc is placed properly in java doc.
+     * @param ast Javadoc root node.
+     * @return true if inheritDoc is valid or false.
+     */
+    private static boolean isOnlyInheritDoc(DetailNode ast) {
+        boolean extraTextFound = false;
+        boolean containsInheritDoc = false;
+        for (DetailNode child : ast.getChildren()) {
+            if (child.getType() == JavadocTokenTypes.TEXT) {
+                if (!child.getText().trim().isEmpty()) {
+                    extraTextFound = true;
+                }
+            }
+            else if (child.getType() == JavadocTokenTypes.JAVADOC_INLINE_TAG) {
+                if (child.getChildren()[1].getType() == JavadocTokenTypes.INHERIT_DOC_LITERAL) {
+                    containsInheritDoc = true;
+                }
+                else {
+                    extraTextFound = true;
+                }
+            }
+            else if (!SKIP_TOKENS.contains(child.getType())) {
+                extraTextFound = true;
+            }
+            if (extraTextFound) {
+                break;
+            }
+        }
+        return containsInheritDoc && !extraTextFound;
+    }
+
     /**
      * Finds and returns first sentence.
      * @param ast Javadoc root node.

src/test/java/com/puppycrawl/tools/checkstyle/checks/javadoc/SummaryJavadocCheckTest.java

@@ -76,6 +76,10 @@ public void testIncorrect() throws Exception {
             "69: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
             "83: " + getCheckMessage(MSG_SUMMARY_JAVADOC),
             "103: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
+            "116: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
+            "121: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
+            "126: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
+            "131: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
         };
         verify(checkConfig, getPath("InputIncorrectSummaryJavaDoc.java"), expected);
     }
@@ -106,6 +110,10 @@ public void testDefaultConfiguration() throws Exception {
             "37: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
             "69: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
             "103: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
+            "116: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
+            "121: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
+            "126: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
+            "131: " + getCheckMessage(MSG_SUMMARY_FIRST_SENTENCE),
         };
 
         createChecker(checkConfig);

src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/InputCorrectSummaryJavaDoc.java

@@ -32,6 +32,22 @@ void foo6() {}
     /** {@inheritDoc} */
     void foo7() {}
 
+    /**
+     * {@inheritDoc} */
+    void foo8() {}
+
+    /**
+     * {@inheritDoc}
+     */
+    void foo9() {}
+
+    /**
+     *
+     *
+     * {@inheritDoc}
+     */
+    void foo10() {}
+
     /** 
      * <a href="mailto:vlad@htmlbook.ru"/> 
      */

src/test/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/InputIncorrectSummaryJavaDoc.java

@@ -112,5 +112,25 @@ void foo5() {}
          * An especially short bit of Javadoc.
          */
         void foo6() {}
+
+         /**
+          * mm{@inheritDoc}
+          */
+         void foo7() {}
+
+         /**
+          * {@inheritDoc}mm
+          */
+         void foo9() {}
+
+         /**
+          * {@link #setBounds(int,int,int,int)}
+          */
+         void foo8() {}
+
+         /**
+          *
+          */
+         void foo10() {}
     };
 }

src/xdocs/config_javadoc.xml

@@ -1581,7 +1581,8 @@ public boolean isSomething()
       <subsection name="Description">
         <p>
           Checks that <a href="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#firstsentence">
-          Javadoc summary sentence</a> does not contain phrases that are not recommended to use.
+          Javadoc summary sentence</a> does not contain phrases that are not recommended to use. Comments that contains
+          only InheritDoc tag are skipped.
         </p>
       </subsection>
 
@@ -1630,6 +1631,21 @@ public boolean isSomething()
 &lt;module name=&quot;SummaryJavadocCheck&quot;&gt;
     &lt;property name=&quot;period&quot; value="。"/&gt;
 &lt;/module&gt;
+        </source>
+        <p>
+          Example of {@inheritDoc} without summary.
+        </p>
+        <source>
+          <![CDATA[
+  public class Test extends Exception {
+    /**
+     * {@inheritDoc}
+     */
+    public String toString(){
+      return "";
+    }
+  }
+        ]]>
         </source>
         <p>
           Example of period property.