Issue checkstyle#8801: Support for all Token Types as a Property Type…

… for Module Metadata

config/spotbugs-exclude.xml

@@ -101,7 +101,7 @@
   </Match>
   <Match>
     <!-- till https://github.com/spotbugs/spotbugs/issues/259 -->
-    <Class name="com.puppycrawl.tools.checkstyle.meta.MetadataGenerator" />
+    <Class name="com.puppycrawl.tools.checkstyle.meta.MetadataGeneratorUtil" />
     <Method name="dumpMetadata" />
     <Bug pattern="RCN_REDUNDANT_NULLCHECK_WOULD_HAVE_BEEN_A_NPE" />
   </Match>

pom.xml

@@ -1135,14 +1135,14 @@
                   <element>CLASS</element>
                   <includes>
                     <include>
-                       com.puppycrawl.tools.checkstyle.meta.MetadataGenerator
+                      com.puppycrawl.tools.checkstyle.meta.MetadataGeneratorUtil
                     </include>
                   </includes>
                   <limits>
                     <limit>
                       <counter>LINE</counter>
                       <value>COVEREDRATIO</value>
-                      <minimum>0.96</minimum>
+                      <minimum>0.87</minimum>
                     </limit>
                     <limit>
                       <counter>BRANCH</counter>

src/main/java/com/puppycrawl/tools/checkstyle/checks/DescendantTokenCheck.java

@@ -85,6 +85,11 @@
  * Type is {@code java.lang.String}.
  * Default value is {@code null}.
  * </li>
+ * <li>
+ * Property {@code tokens} - tokens to check
+ * Type is {@code allTokenTypes}.
+ * Default value is {@code ""}.
+ * </li>
  * </ul>
  * <p>
  * To configure the check to produce a violation on a switch statement with no default case:

src/main/java/com/puppycrawl/tools/checkstyle/meta/JavadocMetadataScraper.java

@@ -46,6 +46,7 @@
  */
 @FileStatefulCheck
 public class JavadocMetadataScraper extends AbstractJavadocCheck {
+
     /** Regular expression for property location in class-level javadocs. */
     private static final Pattern PROPERTY_TAG = Pattern.compile("\\s*Property\\s*");
 
@@ -82,7 +83,7 @@ public class JavadocMetadataScraper extends AbstractJavadocCheck {
 
     /** Regular expression for quotes. */
     private static final Pattern QUOTE_PATTERN = Pattern.compile("\"");
-    
+
     /** Java file extension. */
     private static final String JAVA_FILE_EXTENSION = ".java";
 
@@ -189,14 +190,12 @@ else if (ast.getType() == JavadocTokenTypes.SINCE_LITERAL) {
     @Override
     public void finishJavadocTree(DetailNode rootAst) {
         moduleDetails.setDescription(getDescriptionText());
-        if (isTopLevelClassJavadoc()) {
-            try {
-                XmlMetaWriter.write(moduleDetails);
-            }
-            catch (TransformerException | ParserConfigurationException ex) {
-                throw new IllegalStateException("Failed to write metadata into XML file for "
-                        + "module: " + getModuleSimpleName(), ex);
-            }
+        try {
+            XmlMetaWriter.write(moduleDetails);
+        }
+        catch (TransformerException | ParserConfigurationException ex) {
+            throw new IllegalStateException("Failed to write metadata into XML file for "
+                    + "module: " + getModuleSimpleName(), ex);
         }
     }
 

src/main/java/com/puppycrawl/tools/checkstyle/meta/MetadataGenerator.java → src/main/java/com/puppycrawl/tools/checkstyle/meta/MetadataGeneratorUtil.java

@@ -35,11 +35,12 @@
 import com.puppycrawl.tools.checkstyle.DefaultConfiguration;
 import com.puppycrawl.tools.checkstyle.TreeWalker;
 import com.puppycrawl.tools.checkstyle.api.CheckstyleException;
+import com.puppycrawl.tools.checkstyle.utils.TokenUtil;
 
 /** Class which handles all the metadata generation and writing calls. */
-public final class MetadataGenerator {
+public final class MetadataGeneratorUtil {
 
-    private MetadataGenerator() {
+    private MetadataGeneratorUtil() {
     }
 
     /**
@@ -97,4 +98,15 @@ private static void dumpMetadata(Checker checker, String path) throws Checkstyle
 
         checker.process(validFiles);
     }
+
+    /**
+     * Return all token types present in checkstyle.
+     *
+     * @return list of token type names
+     */
+    public static List<String> fetchAllTokens() {
+        return Arrays.stream(TokenUtil.getAllTokenIds()).asDoubleStream()
+                .mapToObj(tokenId -> TokenUtil.getTokenName((int) tokenId))
+                .collect(Collectors.toList());
+    }
 }

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/DescendantTokenCheck.xml

@@ -46,6 +46,9 @@
                <description>Define the violation message
  when the maximum count is exceeded.</description>
             </property>
+            <property default-value="" name="tokens" type="allTokenTypes">
+               <description>tokens to check</description>
+            </property>
          </properties>
          <message-keys>
             <message-key key="descendant.token.max"/>

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/OrderedPropertiesCheck.xml

@@ -4,22 +4,10 @@
       <check fully-qualified-name="com.puppycrawl.tools.checkstyle.checks.OrderedPropertiesCheck"
              name="OrderedProperties"
              parent="com.puppycrawl.tools.checkstyle.Checker">
-         <description>&lt;p&gt;Detects if keys in properties files are in correct order.&lt;/p&gt;
- &lt;p&gt;
-   Rationale: Sorted properties make it easy for people to find required properties by name
-   in file. It makes merges more easy. While there are no problems at runtime.
-   This check is valuable only on files with string resources where order of lines
-   does not matter at all, but this can be improved.
-   E.g.: checkstyle/src/main/resources/com/puppycrawl/tools/checkstyle/messages.properties
-   You may suppress warnings of this check for files that have an logical structure like
-   build files or log4j configuration files. See SuppressionFilter.
-   {@code
-   &amp;lt;suppress checks="OrderedProperties"
-     files="log4j.properties|ResourceBundle/Bug.*.properties|logging.properties"/&amp;gt;
-   }
- &lt;/p&gt;
- &lt;p&gt;Known limitation: The key should not contain a newline.
- The string compare will work, but not the line number reporting.&lt;/p&gt;</description>
+         <description>Private property implementation that keeps order of properties like in file.
+
+ @noinspection ClassExtendsConcreteCollection, SerializableHasSerializationMethods
+     &lt;EOF&gt;</description>
          <properties>
             <property default-value=".properties"
                       name="fileExtensions"

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/SuppressWarningsHolder.xml

@@ -4,12 +4,7 @@
       <check fully-qualified-name="com.puppycrawl.tools.checkstyle.checks.SuppressWarningsHolder"
              name="SuppressWarningsHolder"
              parent="com.puppycrawl.tools.checkstyle.TreeWalker">
-         <description>&lt;p&gt;
- Maintains a set of check suppressions from {@code @SuppressWarnings} annotations.
- It allows to prevent Checkstyle from reporting violations from parts of code that were
- annotated with {@code @SuppressWarnings} and using name of the check to be excluded.
- You can also define aliases for check names that need to be suppressed.
- &lt;/p&gt;</description>
+         <description>Records a particular suppression for a region of a file. &lt;EOF&gt;</description>
          <properties>
             <property name="aliasList" type="java.lang.String[]">
                <description>Specify aliases for check names that can be used in code

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/TranslationCheck.xml

@@ -4,56 +4,7 @@
       <check fully-qualified-name="com.puppycrawl.tools.checkstyle.checks.TranslationCheck"
              name="Translation"
              parent="com.puppycrawl.tools.checkstyle.Checker">
-         <description>&lt;p&gt;
- Ensures the correct translation of code by checking property files for consistency
- regarding their keys. Two property files describing one and the same context
- are consistent if they contain the same keys. TranslationCheck also can check
- an existence of required translations which must exist in project, if
- {@code requiredTranslations} option is used.
- &lt;/p&gt;
- &lt;p&gt;
- Consider the following properties file in the same directory:
- &lt;/p&gt;
- &lt;pre&gt;
- #messages.properties
- hello=Hello
- cancel=Cancel
-
- #messages_de.properties
- hell=Hallo
- ok=OK
- &lt;/pre&gt;
- &lt;p&gt;
- The Translation check will find the typo in the German {@code hello} key,
- the missing {@code ok} key in the default resource file and the missing
- {@code cancel} key in the German resource file:
- &lt;/p&gt;
- &lt;pre&gt;
- messages_de.properties: Key 'hello' missing.
- messages_de.properties: Key 'cancel' missing.
- messages.properties: Key 'hell' missing.
- messages.properties: Key 'ok' missing.
- &lt;/pre&gt;
- &lt;p&gt;
- Language code for the property {@code requiredTranslations} is composed of
- the lowercase, two-letter codes as defined by
- &lt;a href="https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes"&gt;ISO 639-1&lt;/a&gt;.
- Default value is empty String Set which means that only the existence of default
- translation is checked. Note, if you specify language codes (or just one
- language code) of required translations the check will also check for existence
- of default translation files in project.
- &lt;/p&gt;
- &lt;p&gt;
- Attention: the check will perform the validation of ISO codes if the option
- is used. So, if you specify, for example, "mm" for language code,
- TranslationCheck will rise violation that the language code is incorrect.
- &lt;/p&gt;
- &lt;p&gt;
- Attention: this Check could produce false-positives if it is used with
- &lt;a href="https://checkstyle.org/config.html#Checker"&gt;Checker&lt;/a&gt; that use cache
- (property "cacheFile") This is known design problem, will be addressed at
- &lt;a href="https://github.com/checkstyle/checkstyle/issues/3539"&gt;issue&lt;/a&gt;.
- &lt;/p&gt;</description>
+         <description>Class which represents a resource bundle. &lt;EOF&gt;</description>
          <properties>
             <property default-value=".properties"
                       name="fileExtensions"

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/UniquePropertiesCheck.xml

@@ -4,14 +4,10 @@
       <check fully-qualified-name="com.puppycrawl.tools.checkstyle.checks.UniquePropertiesCheck"
              name="UniqueProperties"
              parent="com.puppycrawl.tools.checkstyle.Checker">
-         <description>&lt;p&gt;
- Detects duplicated keys in properties files.
- &lt;/p&gt;
- &lt;p&gt;
- Rationale: Multiple property keys usually appear after merge or rebase of
- several branches. While there are no problems in runtime, there can be a confusion
- due to having different values for the duplicated properties.
- &lt;/p&gt;</description>
+         <description>Properties subclass to store duplicated property keys in a separate map.
+
+ @noinspection ClassExtendsConcreteCollection, SerializableHasSerializationMethods
+     &lt;EOF&gt;</description>
          <properties>
             <property default-value=".properties"
                       name="fileExtensions"

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/blocks/RightCurlyCheck.xml

@@ -4,17 +4,8 @@
       <check fully-qualified-name="com.puppycrawl.tools.checkstyle.checks.blocks.RightCurlyCheck"
              name="RightCurly"
              parent="com.puppycrawl.tools.checkstyle.TreeWalker">
-         <description>&lt;p&gt;
- Checks the placement of right curly braces ({@code '}'}) for code blocks. This check supports
- if-else, try-catch-finally blocks, while-loops, for-loops,
- method definitions, class definitions, constructor definitions,
- instance, static initialization blocks, annotation definitions and enum definitions.
- For right curly brace of expression blocks of arrays, lambdas and class instances
- please follow issue
- &lt;a href="https://github.com/checkstyle/checkstyle/issues/5945"&gt;#5945&lt;/a&gt;.
- For right curly brace of enum constant please follow issue
- &lt;a href="https://github.com/checkstyle/checkstyle/issues/7519"&gt;#7519&lt;/a&gt;.
- &lt;/p&gt;</description>
+         <description>Structure that contains all details for validation.
+     &lt;EOF&gt;</description>
          <properties>
             <property default-value="same"
                       name="option"

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/coding/DeclarationOrderCheck.xml

@@ -4,45 +4,8 @@
       <check fully-qualified-name="com.puppycrawl.tools.checkstyle.checks.coding.DeclarationOrderCheck"
              name="DeclarationOrder"
              parent="com.puppycrawl.tools.checkstyle.TreeWalker">
-         <description>&lt;p&gt;
- Checks that the parts of a class, record, or interface declaration appear in the order
- suggested by the
- &lt;a href="https://checkstyle.org/styleguides/sun-code-conventions-19990420/CodeConventions.doc2.html#a1852"&gt;
- Code Conventions for the Java Programming Language&lt;/a&gt;.
- &lt;/p&gt;
- &lt;p&gt;
- According to
- &lt;a href="https://checkstyle.org/styleguides/sun-code-conventions-19990420/CodeConventions.doc2.html#a1852"&gt;
- Code Conventions for the Java Programming Language&lt;/a&gt;, the parts of a class
- or interface declaration should appear in the following order:
- &lt;/p&gt;
- &lt;ol&gt;
- &lt;li&gt;
- Class (static) variables. First the public class variables, then
- protected, then package level (no access modifier), and then private.
- &lt;/li&gt;
- &lt;li&gt; Instance variables. First the public class variables, then
- protected, then package level (no access modifier), and then private.
- &lt;/li&gt;
- &lt;li&gt; Constructors &lt;/li&gt;
- &lt;li&gt; Methods &lt;/li&gt;
- &lt;/ol&gt;
- &lt;p&gt;
- Purpose of &lt;b&gt;ignore*&lt;/b&gt; option is to ignore related violations,
- however it still impacts on other class members.
- &lt;/p&gt;
- &lt;p&gt;ATTENTION: the check skips class fields which have
- &lt;a href="https://docs.oracle.com/javase/specs/jls/se11/html/jls-8.html#jls-8.3.3"&gt;
- forward references &lt;/a&gt; from validation due to the fact that we have Checkstyle's limitations
- to clearly detect user intention of fields location and grouping. For example:
- &lt;/p&gt;
- &lt;pre&gt;
- public class A {
-   private double x = 1.0;
-   private double y = 2.0;
-   public double slope = x / y; // will be skipped from validation due to forward reference
- }
- &lt;/pre&gt;</description>
+         <description>Private class to encapsulate the state.
+     &lt;EOF&gt;</description>
          <properties>
             <property default-value="false" name="ignoreConstructors" type="boolean">
                <description>control whether to ignore constructors.</description>

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/coding/EqualsAvoidNullCheck.xml

@@ -4,31 +4,8 @@
       <check fully-qualified-name="com.puppycrawl.tools.checkstyle.checks.coding.EqualsAvoidNullCheck"
              name="EqualsAvoidNull"
              parent="com.puppycrawl.tools.checkstyle.TreeWalker">
-         <description>&lt;p&gt;
- Checks that any combination of String literals
- is on the left side of an {@code equals()} comparison.
- Also checks for String literals assigned to some field
- (such as {@code someString.equals(anotherString = "text")}).
- &lt;/p&gt;
- &lt;p&gt;Rationale: Calling the {@code equals()} method on String literals
- will avoid a potential {@code NullPointerException}. Also, it is
- pretty common to see null checks right before equals comparisons,
- which is not necessary in the example below.
- &lt;/p&gt;
- &lt;p&gt;
- For example, this code:
- &lt;/p&gt;
- &lt;pre&gt;
- String nullString = null;
- nullString.equals(&amp;quot;My_Sweet_String&amp;quot;);
- &lt;/pre&gt;
- &lt;p&gt;
- should be refactored to:
- &lt;/p&gt;
- &lt;pre&gt;
- String nullString = null;
- &amp;quot;My_Sweet_String&amp;quot;.equals(nullString);
- &lt;/pre&gt;</description>
+         <description>Holds the names of fields of a type.
+     &lt;EOF&gt;</description>
          <properties>
             <property default-value="false" name="ignoreEqualsIgnoreCase" type="boolean">
                <description>Control whether to ignore

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/coding/FinalLocalVariableCheck.xml

@@ -4,14 +4,7 @@
       <check fully-qualified-name="com.puppycrawl.tools.checkstyle.checks.coding.FinalLocalVariableCheck"
              name="FinalLocalVariable"
              parent="com.puppycrawl.tools.checkstyle.TreeWalker">
-         <description>&lt;p&gt;
- Checks that local variables that never have their values changed are declared final.
- The check can be configured to also check that unchanged parameters are declared final.
- &lt;/p&gt;
- &lt;p&gt;
- When configured to check parameters, the check ignores parameters of interface
- methods and abstract methods.
- &lt;/p&gt;</description>
+         <description>Represents information about final local variable candidate. &lt;EOF&gt;</description>
          <properties>
             <property default-value="false"
                       name="validateEnhancedForLoopVariable"

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/coding/HiddenFieldCheck.xml

@@ -4,44 +4,8 @@
       <check fully-qualified-name="com.puppycrawl.tools.checkstyle.checks.coding.HiddenFieldCheck"
              name="HiddenField"
              parent="com.puppycrawl.tools.checkstyle.TreeWalker">
-         <description>&lt;p&gt;
- Checks that a local variable or a parameter does not shadow
- a field that is defined in the same class.
- &lt;/p&gt;
- &lt;p&gt;
- It is possible to configure the check to ignore all property setter methods.
- &lt;/p&gt;
- &lt;p&gt;
- A method is recognized as a setter if it is in the following form
- &lt;/p&gt;
- &lt;pre&gt;
- ${returnType} set${Name}(${anyType} ${name}) { ... }
- &lt;/pre&gt;
- &lt;p&gt;
- where ${anyType} is any primitive type, class or interface name;
- ${name} is name of the variable that is being set and ${Name} its
- capitalized form that appears in the method name. By default it is expected
- that setter returns void, i.e. ${returnType} is 'void'. For example
- &lt;/p&gt;
- &lt;pre&gt;
- void setTime(long time) { ... }
- &lt;/pre&gt;
- &lt;p&gt;
- Any other return types will not let method match a setter pattern. However,
- by setting &lt;em&gt;setterCanReturnItsClass&lt;/em&gt; property to &lt;em&gt;true&lt;/em&gt;
- definition of a setter is expanded, so that setter return type can also be
- a class in which setter is declared. For example
- &lt;/p&gt;
- &lt;pre&gt;
- class PageBuilder {
-   PageBuilder setName(String name) { ... }
- }
- &lt;/pre&gt;
- &lt;p&gt;
- Such methods are known as chain-setters and a common when Builder-pattern
- is used. Property &lt;em&gt;setterCanReturnItsClass&lt;/em&gt; has effect only if
- &lt;em&gt;ignoreSetter&lt;/em&gt; is set to true.
- &lt;/p&gt;</description>
+         <description>Holds the names of static and instance fields of a type.
+     &lt;EOF&gt;</description>
          <properties>
             <property name="ignoreFormat" type="java.util.regex.Pattern">
                <description>Define the RegExp for names of variables