Fixed different behavior between @param and @SInCE

Vladimir.Shapkin · Vladimir.Shapkin · commit 8c8068c5466b · 2024-07-04T17:42:09.000+04:00
The @param regex allows varying numbers of spaces before and after the @param tag, while the @SInCE tag only allows one space before and one after it.
diff --git a/qulice-checkstyle/src/main/java/com/qulice/checkstyle/JavadocTagsCheck.java b/qulice-checkstyle/src/main/java/com/qulice/checkstyle/JavadocTagsCheck.java
@@ -36,9 +36,7 @@
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collection;
-import java.util.HashMap;
 import java.util.List;
-import java.util.Map;
 import java.util.regex.Pattern;
 
 /**
@@ -69,7 +67,7 @@ public final class JavadocTagsCheck extends AbstractCheck {
     /**
      * Map of tag and its pattern.
      */
-    private final Map<String, Pattern> tags = new HashMap<>();
+    private final List<RequiredJavaDocTag> required = new ArrayList<>(1);
 
     /**
      * List of prohibited javadoc tags.
@@ -97,10 +95,13 @@ public int[] getRequiredTokens() {
 
     @Override
     public void init() {
-        this.tags.put(
-            "since",
-            Pattern.compile(
+        this.required.add(
+            new RequiredJavaDocTag(
+                "since",
+                Pattern.compile(
                 "^\\d+(\\.\\d+){1,2}(\\.[0-9A-Za-z-]+(\\.[0-9A-Za-z-]+)*)?$"
+                ),
+                this::log
             )
         );
     }
@@ -115,25 +116,14 @@ public void visitToken(final DetailAST ast) {
             for (final String tag : this.prohibited) {
                 this.findProhibited(lines, start, cstart, cend, tag);
             }
-            for (final String tag : this.tags.keySet()) {
-                this.matchTagFormat(lines, cstart, cend, tag);
+            for (final RequiredJavaDocTag tag : this.required) {
+                tag.matchTagFormat(lines, cstart, cend);
             }
         } else {
             this.log(0, "Problem finding class/interface comment");
         }
     }
 
-    /**
-     * Get the text of the given tag.
-     * @param line Line with the tag.
-     * @return The text of the tag.
-     */
-    private static String getTagText(final String line) {
-        return line.substring(
-            line.indexOf(' ', line.indexOf('@')) + 1
-        );
-    }
-
     /**
      * Find a text in lines, by going up.
      * @param lines List of lines to check.
@@ -195,38 +185,6 @@ private void findProhibited(final String[] lines, final int start,
         }
     }
 
-    /**
-     * Check if the tag text matches the format from pattern.
-     * @param lines List of all lines.
-     * @param start Line number where comment starts.
-     * @param end Line number where comment ends.
-     * @param tag Name of the tag.
-     * @checkstyle ParameterNumber (3 lines)
-     */
-    private void matchTagFormat(final String[] lines, final int start,
-        final int end, final String tag) {
-        final List<Integer> found = this.findTagLineNum(lines, start, end, tag);
-        if (found.isEmpty()) {
-            this.log(
-                start + 1,
-                "Missing ''@{0}'' tag in class/interface comment",
-                tag
-            );
-            return;
-        }
-        for (final Integer item : found) {
-            final String text = JavadocTagsCheck.getTagText(lines[item]);
-            if (!this.tags.get(tag).matcher(text).matches()) {
-                this.log(
-                    item + 1,
-                    "Tag text ''{0}'' does not match the pattern ''{1}''",
-                    text,
-                    this.tags.get(tag).toString()
-                );
-            }
-        }
-    }
-
     /**
      * Find given tag in comment lines.
      * @param lines Lines to search for the tag.
diff --git a/qulice-checkstyle/src/main/java/com/qulice/checkstyle/RequiredJavaDocTag.java b/qulice-checkstyle/src/main/java/com/qulice/checkstyle/RequiredJavaDocTag.java
@@ -0,0 +1,188 @@
+/*
+ * Copyright (c) 2011-2024 Qulice.com
+ *
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met: 1) Redistributions of source code must retain the above
+ * copyright notice, this list of conditions and the following
+ * disclaimer. 2) Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following
+ * disclaimer in the documentation and/or other materials provided
+ * with the distribution. 3) Neither the name of the Qulice.com nor
+ * the names of its contributors may be used to endorse or promote
+ * products derived from this software without specific prior written
+ * permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
+ * NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
+ * THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+ * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+ * OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.qulice.checkstyle;
+
+import java.util.HashMap;
+import java.util.Map;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+/**
+ * Check the required JavaDoc tag in the lines.
+ * <p>Correct format is the following (of a class javadoc):
+ *
+ * <pre>
+ * &#47;**
+ *  * This is my new class.
+ *  *
+ *  * &#64;since 0.3
+ *  *&#47;
+ * public final class Foo {
+ *     &#47;**
+ *      * This is my other class.
+ *      *
+ *      *    &#64;since    0.3
+ *      *&#47;
+ *     public final class Boo {
+ *     // ...
+ * </pre>
+ *
+ * <p>"&#36;Id&#36;" will be replaced by a full text automatically
+ * by Subversion as explained in their documentation (see link below).
+ *
+ * @see <a href="http://svnbook.red-bean.com/en/1.4/svn.advanced.props.special.keywords.html">Keywords substitution in Subversion</a>
+
+ * @since 0.23.1
+ */
+final class RequiredJavaDocTag {
+    /**
+     * Tag name.
+     */
+    private final String name;
+
+    /**
+     * Pattern for searching a tag in a string.
+     */
+    private final Pattern tag;
+
+    /**
+     * Pattern for checking the contents of a tag in a string.
+     */
+    private final Pattern content;
+
+    /**
+     * Reference to a method for writing a message to the log.
+     */
+    private final LogWriter writer;
+
+    /**
+     * Ctor.
+     * @param name Tag name.
+     * @param patt Pattern for checking the contents of a tag in a string.
+     * @param lwriter Reference to a method for writing a message to the log.
+     */
+    RequiredJavaDocTag(final String name, final Pattern patt,
+        final LogWriter lwriter) {
+        this(
+            name,
+            Pattern.compile(
+                String.format(
+                    "(?<name>^ +\\* +@%s)( +)(?<cont>.*)",
+                    name
+                )
+            ),
+            patt,
+            lwriter
+        );
+    }
+
+    /**
+     * Ctor.
+     * @param cname Tag name.
+     * @param ptag Pattern for searching a tag in a string.
+     * @param patt Pattern for checking the contents of a tag in a string.
+     * @param lwriter Reference to a method for writing a message to the log.
+     * @checkstyle ParameterNumberCheck (3 lines)
+     */
+    RequiredJavaDocTag(final String cname, final Pattern ptag,
+        final Pattern patt, final LogWriter lwriter) {
+        this.name = cname;
+        this.tag = ptag;
+        this.content = patt;
+        this.writer = lwriter;
+    }
+
+    /**
+     * Check if the tag text matches the format from pattern.
+     * @param lines List of all lines.
+     * @param start Line number where comment starts.
+     * @param end Line number where comment ends.
+     */
+    public void matchTagFormat(final String[] lines, final int start,
+        final int end) {
+        final Map<Integer, String> found = new HashMap<>(1);
+        for (int pos = start; pos <= end; pos += 1) {
+            final String line = lines[pos];
+            final Matcher matcher = this.tag.matcher(line);
+            if (matcher.matches()
+                && !RequiredJavaDocTag.empty(matcher.group("name"))
+                && !RequiredJavaDocTag.empty(matcher.group("cont"))
+            ) {
+                found.put(pos, matcher.group("cont"));
+                break;
+            }
+        }
+        if (found.isEmpty()) {
+            this.writer.log(
+                start + 1,
+                "Missing ''@{0}'' tag in class/interface comment",
+                this.name
+            );
+        } else {
+            for (final Map.Entry<Integer, String> item : found.entrySet()) {
+                if (!this.content.matcher(item.getValue()).matches()) {
+                    this.writer.log(
+                        item.getKey() + 1,
+                        "Tag text ''{0}'' does not match the pattern ''{1}''",
+                        item.getValue(),
+                        this.content.toString()
+                    );
+                }
+            }
+        }
+    }
+
+    /**
+     * Checks for an empty string.
+     * @param str Line to check.
+     * @return True if str is empty.
+     */
+    private static boolean empty(final String str) {
+        return str == null || str.isBlank();
+    }
+
+    /**
+     * Logger.
+     * @see com.puppycrawl.tools.checkstyle.api.AbstractCheck.log
+     * @since 0.23.1
+     */
+    interface LogWriter {
+        /**
+         * Log a message that has no column information.
+         *
+         * @param line The line number where the audit event was found.
+         * @param msg The message that describes the audit event.
+         * @param args The details of the message.
+         * @see java.text.MessageFormat
+         */
+        void log(int line, String msg, Object... args);
+    }
+}
diff --git a/qulice-checkstyle/src/main/resources/com/qulice/checkstyle/checks.xml b/qulice-checkstyle/src/main/resources/com/qulice/checkstyle/checks.xml
@@ -104,25 +104,25 @@ OF THE POSSIBILITY OF SUCH DAMAGE.
   JavaDoc regexp checks
   -->
   <module name="RegexpSingleline">
-    <property name="format" value="\* +@return +[^A-Z]"/>
+    <property name="format" value="\* +@return +[^A-Z ]"/>
     <property name="fileExtensions" value="java"/>
     <property name="id" value="ReturnShouldStartWithCapitalLetter"/>
     <property name="message" value="@return tag description should start with capital letter"/>
   </module>
   <module name="RegexpSingleline">
-    <property name="format" value="\* +@param +\w+ +[^A-Z]"/>
+    <property name="format" value="\* +@param +\w+ +[^A-Z ]"/>
     <property name="fileExtensions" value="java"/>
     <property name="id" value="ParamShouldStartWithCapitalLetter"/>
     <property name="message" value="@param tag description should start with capital letter"/>
   </module>
   <module name="RegexpSingleline">
-    <property name="format" value="/\*\* +[^A-Z\{]"/>
+    <property name="format" value="/\*\* +[^A-Z\{ ]"/>
     <property name="fileExtensions" value="java"/>
     <property name="id" value="FirstLetterInCommentShouldBeCapital"/>
     <property name="message" value="First sentence in a comment should start with a capital letter"/>
   </module>
   <module name="RegexpMultiline">
-    <property name="format" value="/\*\*\W+\* +[^A-Z\{]"/>
+    <property name="format" value="/\*\*\W+\* +[^A-Z\{ ]"/>
     <property name="fileExtensions" value="java"/>
     <property name="id" value="FirstLetterInCommentShouldBeCapital2"/>
     <property name="message" value="First sentence in a comment should start with a capital letter"/>
diff --git a/qulice-checkstyle/src/test/java/com/qulice/checkstyle/CheckstyleValidatorTest.java b/qulice-checkstyle/src/test/java/com/qulice/checkstyle/CheckstyleValidatorTest.java
@@ -48,7 +48,6 @@
 import org.hamcrest.TypeSafeMatcher;
 import org.hamcrest.collection.IsIterableContainingInOrder;
 import org.junit.jupiter.api.BeforeEach;
-import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 
 /**
@@ -776,7 +775,6 @@ void allowsUppercaseAbbreviationExceptions() throws Exception {
      *
      * @throws Exception In case of error
      */
-    @Disabled
     @Test
     void checkLambdaAndGenericsAtEndOfLine() throws Exception {
         this.runValidation("ValidLambdaAndGenericsAtEndOfLine.java", true);
diff --git a/qulice-checkstyle/src/test/java/com/qulice/checkstyle/RequiredJavaDocTagTest.java b/qulice-checkstyle/src/test/java/com/qulice/checkstyle/RequiredJavaDocTagTest.java
diff --git a/qulice-checkstyle/src/test/resources/com/qulice/checkstyle/ValidLiteralComparisonCheck.java b/qulice-checkstyle/src/test/resources/com/qulice/checkstyle/ValidLiteralComparisonCheck.java
