Issue checkstyle#3907: SummaryJavadoc no violation on javadoc where '…

….' is used not as end of sentence

src/it/java/com/google/checkstyle/test/chapter7javadoc/rule72thesummaryfragment/SummaryJavadocTest.java

@@ -56,15 +56,20 @@ public void testIncorrect() throws Exception {
             "summary.first.sentence");
         final String msgForbiddenFragment = getCheckMessage(SummaryJavadocCheck.class,
             "summary.javaDoc");
+        final String msgMissingDoc = getCheckMessage(SummaryJavadocCheck.class,
+            "summary.javaDoc.missing");
 
         final String[] expected = {
-            "14: " + msgFirstSentence,
+            "14: " + msgMissingDoc,
+            "32: " + msgMissingDoc,
             "37: " + msgFirstSentence,
             "47: " + msgForbiddenFragment,
+            "53: " + msgMissingDoc,
             "58: " + msgForbiddenFragment,
-            "69: " + msgFirstSentence,
+            "58: " + msgMissingDoc,
+            "69: " + msgMissingDoc,
             "83: " + msgForbiddenFragment,
-            "103: " + msgFirstSentence,
+            "103: " + msgMissingDoc,
         };
 
         final Configuration checkConfig = getCheckConfig("SummaryJavadoc");

src/it/resources/com/google/checkstyle/test/chapter7javadoc/rule72thesummaryfragment/InputCorrectSummaryJavaDocCheck.java

@@ -16,6 +16,7 @@ class InputCorrectSummaryJavaDocCheck {
     void foo3() {}
 
     /**
+     * This is valid.
      * @throws Exception if an error occurs.
      */
     void foo4() throws Exception {}
@@ -29,8 +30,9 @@ void foo5() {}
      */
     void foo6() {}
 
-    /** 
-     * <a href="mailto:vlad@htmlbook.ru"/> 
+    /**
+     * This is valid.
+     * <a href="mailto:vlad@htmlbook.ru"/>
      */
      class InnerInputCorrectJavaDocParagraphCheck {
 
@@ -46,11 +48,12 @@ class InnerInputCorrectJavaDocParagraphCheck {
         public static final byte NUL_2 = 0;
 
         /**
-         * Returns the customer ID. This method returns
+         * Returns the customer ID. This method returns.
          */
         int getId() {return 666;}
 
         /**
+         * This is valid.
          * <a href="mailto:vlad@htmlbook.ru"/>.
          */
         void foo2() {}
@@ -62,6 +65,7 @@ void foo2() {}
         void foo3() {}
 
         /**
+         * This is valid.
          * @throws Exception if an error occurs.
          */
         void foo4() throws Exception {}
@@ -74,7 +78,7 @@ void foo5() {}
 
         /**
          * An especially short (int... A) bit of Javadoc. This
-         * method returns
+         * method returns.
          */
         void foo6() {}
     }
@@ -105,6 +109,7 @@ void foo6() {}
         void foo3() {}
 
         /**
+         * This is valid.
          * @throws Exception if an error occurs.
          */
         void foo4() throws Exception {}
@@ -128,6 +133,7 @@ void foo6() {}
         boolean emulated1() {return false;}
 
         /**
+         * This is valid.
          * @return Some Javadoc the customer ID.
          */
         int geId() {return 666;} 

src/it/resources/com/google/checkstyle/test/chapter7javadoc/rule72thesummaryfragment/InputIncorrectSummaryJavaDocCheck.java

@@ -29,7 +29,7 @@ void foo6() {}
      */
     public static final byte NUL = 0;
 
-    /** 
+/*warn*//**
      * <a href="mailto:vlad@htmlbook.ru"/> 
      */
      class InnerInputCorrectJavaDocParagraphCheck {
@@ -39,7 +39,7 @@ class InnerInputCorrectJavaDocParagraphCheck {
           */
         public static final byte NUL = 0;
 
-        /** 
+        /**
          * Some java@doc.
          */
         public static final byte NUL_2 = 0;
@@ -50,7 +50,7 @@ class InnerInputCorrectJavaDocParagraphCheck {
          */
         boolean emulated() {return false;}
 
-        /**
+/*warn*//**
          * <a href="mailto:vlad@htmlbook.ru"/>
          */
         void foo2() {}
@@ -62,7 +62,7 @@ void foo2() {}
         int geId() {return 666;} 
 
         /**
-         * As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
+         * As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}.
          */
         void foo3() {}
 
@@ -85,32 +85,32 @@ void foo6() {}
       */
     InnerInputCorrectJavaDocParagraphCheck anon = new InnerInputCorrectJavaDocParagraphCheck() {
 
-        /**
-         * Some Javadoc.
-         */
-        public static final byte NUL = 0;
+            /**
+             * Some Javadoc.
+             */
+            public static final byte NUL = 0;
+
+            /**
+             * Some Javadoc.
+             */
+            void emulated(String s) {}
+
+            /**
+             * As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}.
+             */
+            void foo3() {}
 
-        /**
-         * Some Javadoc.
-         */
-        void emulated(String s) {}
-
-        /**
-         * As of JDK 1.1, replaced by {@link #setBounds(int,int,int,int)}
-         */
-        void foo3() {}
-
 /*warn*//**
-         * @throws Exception if an error occurs
-         */
-        void foo4() throws Exception {}
-
-        /** An especially short bit of Javadoc. */
-        void foo5() {}
+             * @throws Exception if an error occurs
+             */
+            void foo4() throws Exception {}
 
-        /**
-         * An especially short bit of Javadoc.
-         */
-        void foo6() {}
-    };
+            /** An especially short bit of Javadoc. */
+            void foo5() {}
+
+            /**
+             * An especially short bit of Javadoc.
+             */
+            void foo6() {}
+        };
 }

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

@@ -19,7 +19,6 @@
 
 package com.puppycrawl.tools.checkstyle.checks.javadoc;
 
-import java.util.Arrays;
 import java.util.HashSet;
 import java.util.Set;
 import java.util.regex.Pattern;
@@ -29,6 +28,7 @@
 import com.puppycrawl.tools.checkstyle.api.JavadocTokenTypes;
 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
 import com.puppycrawl.tools.checkstyle.utils.CommonUtils;
+import com.puppycrawl.tools.checkstyle.utils.JavadocUtils;
 
 /**
  * <p>
@@ -76,6 +76,11 @@ public class SummaryJavadocCheck extends AbstractJavadocCheck {
      * file.
      */
     public static final String MSG_SUMMARY_JAVADOC = "summary.javaDoc";
+    /**
+     * A key is pointing to the warning message text in "messages.properties"
+     * file.
+     */
+    public static final String MSG_SUMMARY_JAVADOC_MISSING = "summary.javaDoc.missing";
     /**
      * This regexp is used to convert multiline javadoc to single line without stars.
      */
@@ -85,14 +90,9 @@ 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)
-    );
+    /** Inherit doc literal. */
+    private static final String INHERIT_DOC = "{@inheritDoc}";
+
     /**
      * Regular expression for forbidden summary fragments.
      */
@@ -145,12 +145,8 @@ public int[] getRequiredTokens() {
     public void visitJavadocToken(DetailNode ast) {
         String firstSentence = getFirstSentence(ast);
         final int endOfSentence = firstSentence.lastIndexOf(period);
-        if (endOfSentence == -1) {
-            if (!isOnlyInheritDoc(ast)) {
-                log(ast.getLineNumber(), MSG_SUMMARY_FIRST_SENTENCE);
-            }
-        }
-        else {
+        checkPeriodAtEnd(ast);
+        if (endOfSentence != -1) {
             firstSentence = firstSentence.substring(0, endOfSentence);
             if (containsForbiddenFragment(firstSentence)) {
                 log(ast.getLineNumber(), MSG_SUMMARY_JAVADOC);
@@ -159,35 +155,101 @@ public void visitJavadocToken(DetailNode ast) {
     }
 
     /**
-     * Finds if inheritDoc is placed properly in java doc.
+     * Checks if period is at the end of sentence.
      * @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;
+    private void checkPeriodAtEnd(DetailNode ast) {
+        final Set<Integer> allowedTypes = new HashSet<>();
+        allowedTypes.add(JavadocTokenTypes.TEXT);
+        allowedTypes.add(JavadocTokenTypes.WS);
+        boolean flag = true;
+        boolean periodFound = false;
+        final StringBuilder result = new StringBuilder();
         for (DetailNode child : ast.getChildren()) {
-            if (child.getType() == JavadocTokenTypes.TEXT) {
-                if (!CommonUtils.isBlank(child.getText())) {
-                    extraTextFound = true;
-                }
+            if (allowedTypes.contains(child.getType())) {
+                result.append(child.getText());
+            }
+            else if (child.getType() == JavadocTokenTypes.JAVADOC_INLINE_TAG
+                    && getContentOfChild(child).equals(INHERIT_DOC)) {
+                result.append(INHERIT_DOC);
             }
-            else if (child.getType() == JavadocTokenTypes.JAVADOC_INLINE_TAG) {
-                if (child.getChildren()[1].getType() == JavadocTokenTypes.INHERIT_DOC_LITERAL) {
-                    containsInheritDoc = true;
-                }
-                else {
-                    extraTextFound = true;
-                }
+            else if (child.getType() == JavadocTokenTypes.HTML_ELEMENT
+                    && result.toString().trim().equals("")) {
+                getStringInsideTag(result, child.getChildren()[0].getChildren()[0]);
             }
-            else if (!SKIP_TOKENS.contains(child.getType())) {
-                extraTextFound = true;
+            else if (child.getType() == JavadocTokenTypes.JAVADOC_TAG) {
+                flag = false;
             }
-            if (extraTextFound) {
+            else if (isPeriodAtEnd(result, child)) {
+                periodFound = true;
+            }
+            if (!flag) {
                 break;
             }
         }
-        return containsInheritDoc && !extraTextFound;
+        printWarningForViolation(ast, periodFound, result);
+    }
+
+    /**
+     * Returns content when token type is javadoc inline tag.
+     * @param child javadoc inline tag ast.
+     * @return content of child nodes as string.
+     */
+    private static String getContentOfChild(DetailNode child) {
+        final StringBuilder contents = new StringBuilder();
+        for (DetailNode node : child.getChildren()) {
+            contents.append(node.getText().trim());
+        }
+        return contents.toString();
+    }
+
+    /**
+     * Concatenates string within text of html tags.
+     * @param result javadoc string
+     * @param detailNode javadoc tag node
+     */
+    private void getStringInsideTag(StringBuilder result, DetailNode detailNode) {
+        DetailNode tempNode = detailNode;
+        while (tempNode != null) {
+            if (tempNode.getType() == JavadocTokenTypes.TEXT) {
+                result.append(tempNode.getText());
+            }
+            tempNode = JavadocUtils.getNextSibling(tempNode);
+        }
+    }
+
+    /**
+     * Checks if period is set at end of first sentence.
+     * @param result javadoc string
+     * @param child child node
+     * @return true if period is at end of first sentence.
+     */
+    private boolean isPeriodAtEnd(StringBuilder result, DetailNode child) {
+        return child.getType() == JavadocTokenTypes.NEWLINE
+                && !result.toString().trim().equals("")
+                && String.valueOf(result.toString().trim()
+                    .charAt(result.toString().trim().length() - 1)).equals(period);
+    }
+
+    /**
+     * Finds if javadoc ends with period or not.
+     * @param ast ast Javadoc root node.
+     * @param periodFound true if period is found in sentence before end of line
+     * @param result javadoc string
+     */
+    private void printWarningForViolation(DetailNode ast,
+                                          boolean periodFound,
+                                          StringBuilder result) {
+        final String str = result.toString().replace('*', ' ').trim();
+        if (str.isEmpty()) {
+            log(ast.getLineNumber(), MSG_SUMMARY_JAVADOC_MISSING);
+        }
+        else if (!periodFound
+                    && !period.isEmpty()
+                    && !str.contains(period)
+                    && !str.equals(INHERIT_DOC)) {
+            log(ast.getLineNumber(), MSG_SUMMARY_FIRST_SENTENCE);
+        }
     }
 
     /**

src/main/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/messages.properties

@@ -30,6 +30,7 @@ non.empty.atclause=At-clause should have a non-empty description.
 tag.continuation.indent=Line continuation have incorrect indentation level, expected level should be {0}.
 
 summary.javaDoc=Forbidden summary fragment.
+summary.javaDoc.missing=Summary javadoc is missing.
 summary.first.sentence=First sentence of Javadoc is incomplete (period is missing) or not present.
 
 at.clause.order=At-clauses have to appear in the order ''{0}''.

src/main/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/messages_de.properties

@@ -30,6 +30,7 @@ non.empty.atclause=@-Klausel sollte eine nicht-leere Beschreibung haben.
 tag.continuation.indent=Forsetzung der Zeile hat falsche Einrückungstiefe (erwartet: {0}).
 
 summary.javaDoc=Verbotener Ausdruck im ersten Javadoc-Satz.
+summary.javaDoc.missing=Zusammenfassung javadoc fehlt.
 summary.first.sentence=Erster Javadoc-Satz ist unvollständig (Punkt fehlt) oder nicht vorhanden.
 
 at.clause.order=@-Klauseln müssen in der folgenden Reihenfolge erscheinen: ''{0}''.

src/main/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/messages_es.properties

@@ -30,6 +30,7 @@ non.empty.atclause = Al cláusula debe tener una descripción que no esté vací
 tag.continuation.indent = Línea continuación tiene nivel de sangría incorrecta, nivel esperado debería ser {0}
 
 summary.javaDoc = Resumen fragmento Prohibida.
+summary.javaDoc.missing=Resumen javadoc falta.
 summary.first.sentence = Primera frase del Javadoc es incompleta (período de falta) o no está presente.
 
 at.clause.order = Al-cláusulas tienen que aparecer en el orden ''{0}''.

src/main/resources/com/puppycrawl/tools/checkstyle/checks/javadoc/messages_fi.properties

@@ -30,6 +30,7 @@ non.empty.atclause = At-lauseke tulisi olla ei-tyhjä kuvaus.
 tag.continuation.indent = Jatkorivin on väärä sisennystason, odotettu taso olisi {0} .
 
 summary.javaDoc = Kielletty yhteenveto fragmentti.
+summary.javaDoc.missing=Yhteenveto javadoc puuttuu.
 summary.first.sentence = Ensimmäinen virke Javadoc on epätäydellinen (ajanjakso puuttuu) tai ole läsnä.
 
 at.clause.order = At-lausekkeet tarvitse esiintyä järjestyksessä ''{0}''.