Issue checkstyle#6336: added javadoc for Test Support classes

config/suppressions.xml

@@ -34,14 +34,6 @@
                     |NestedIfDepth|MethodLength"
              files="[\\/]XdocsPagesTest\.java"/>
 
-  <!-- till https://github.com/checkstyle/checkstyle/issues/6336 -->
-  <suppress checks="JavadocMethod" files=".*AbstractIndentationTestSupport\.java"/>
-  <suppress checks="JavadocMethod" files=".*AbstractModuleTestSupport\.java"/>
-  <suppress checks="JavadocMethod" files=".*AbstractXpathTestSupport\.java"/>
-  <suppress checks="JavadocMethod" files=".*AbstractModuleTestSupport\.java"/>
-  <suppress checks="JavadocMethod" files=".*AbstractPathTestSupport\.java"/>
-  <suppress checks="JavadocMethod" files=".*AbstractXmlTestSupport\.java"/>
-
   <!-- The Check generates too many violations, fixing them will make code unmanageable. -->
   <suppress checks="MagicNumber" files="(ParseTreeTablePresentation|MainFrame)\.java"/>
 

src/it/java/com/google/checkstyle/test/base/AbstractIndentationTestSupport.java

@@ -60,6 +60,16 @@ protected Integer[] getLinesWithWarn(String fileName) throws IOException {
         return getLinesWithWarnAndCheckComments(fileName, TAB_WIDTH);
     }
 
+    /**
+     * Returns line numbers for lines with 'warn' comments.
+     *
+     * @param aFileName file name.
+     * @param tabWidth tab width.
+     * @return array of line numbers containing 'warn' comments ('warn').
+     * @throws IOException while reading the file for checking lines.
+     * @throws IllegalStateException if file has incorrect indentation in comment or
+     *     comment is inconsistent or if file has no indentation comment.
+     */
     private static Integer[] getLinesWithWarnAndCheckComments(String aFileName,
             final int tabWidth)
                     throws IOException {
@@ -109,16 +119,37 @@ else if (NONEMPTY_LINE_REGEX.matcher(line).matches()) {
         return result.toArray(new Integer[0]);
     }
 
+    /**
+     * Returns amount of indentation from the comment.
+     *
+     * @param comment the indentation comment to be checked.
+     * @return amount of indentation in comment.
+     */
     private static int getIndentFromComment(String comment) {
         final Matcher match = GET_INDENT_FROM_COMMENT_REGEX.matcher(comment);
         match.matches();
         return Integer.parseInt(match.group(1));
     }
 
+    /**
+     * Checks if comment is a warn comment (ends with "warn") or not.
+     *
+     * @param comment the comment to be checked.
+     * @return true if comment ends with " warn" else returns false.
+     */
     private static boolean isWarnComment(String comment) {
         return comment.endsWith(" warn");
     }
 
+    /**
+     * Checks if a comment of comment type is consistent or not.
+     *
+     * @param comment the comment to be checked.
+     * @return true if comment is consistent based on expected indent level, actual indent level
+     *     and if comment is a warn comment else it returns false.
+     * @throws IllegalArgumentException if comment type is unknown and cannot determine consistency.
+     * @throws IllegalStateException if cannot determine that comment is consistent(default case).
+     */
     private static boolean isCommentConsistent(String comment) {
         final int indentInComment = getIndentFromComment(comment);
         final boolean isWarnComment = isWarnComment(comment);
@@ -147,6 +178,14 @@ private static boolean isCommentConsistent(String comment) {
         return result;
     }
 
+    /**
+     * Checks if a Non Strict Comment is consistent or not.
+     *
+     * @param comment the comment to be checked.
+     * @param indentInComment the actual indentation in that comment.
+     * @param isWarnComment if comment is Warn comment or not.
+     * @return true if Non Strict comment is consistent else returns false.
+     */
     private static boolean isNonStrictCommentConsistent(String comment,
             int indentInComment, boolean isWarnComment) {
         final Matcher nonStrictLevelMatch = NON_STRICT_LEVEL_COMMENT_REGEX.matcher(comment);
@@ -157,6 +196,14 @@ private static boolean isNonStrictCommentConsistent(String comment,
                 || indentInComment < expectedMinimalIndent && isWarnComment;
     }
 
+    /**
+     * Checks if a Single Level comment is consistent or not.
+     *
+     * @param comment the comment to be checked.
+     * @param indentInComment the actual indentation in that comment.
+     * @param isWarnComment if comment is Warn comment or not.
+     * @return true if Single Level comment is consistent or not else returns false.
+     */
     private static boolean isSingleLevelCommentConsistent(String comment,
             int indentInComment, boolean isWarnComment) {
         final Matcher singleLevelMatch = SINGLE_LEVEL_COMMENT_REGEX.matcher(comment);
@@ -167,6 +214,14 @@ private static boolean isSingleLevelCommentConsistent(String comment,
                 || expectedLevel != indentInComment && isWarnComment;
     }
 
+    /**
+     * Checks if a Multi-Level comment is consistent or not.
+     *
+     * @param comment the comment to be checked.
+     * @param indentInComment the actual indentation in that comment.
+     * @param isWarnComment if comment is Warn comment or not.
+     * @return true if Multi-Level comment is consistent or not else returns false.
+     */
     private static boolean isMultiLevelCommentConsistent(String comment,
             int indentInComment, boolean isWarnComment) {
         final Matcher multilevelMatch = MULTILEVEL_COMMENT_REGEX.matcher(comment);
@@ -180,6 +235,14 @@ private static boolean isMultiLevelCommentConsistent(String comment,
                 || !containsActualLevel && isWarnComment;
     }
 
+    /**
+     * Returns the type of Comment by matching with specific regex for each type.
+     * Possible types include {@link CommentType#MULTILEVEL}, {@link CommentType#SINGLE_LEVEL},
+     * {@link CommentType#NON_STRICT_LEVEL}, and {@link CommentType#UNKNOWN}.
+     *
+     * @param comment the comment whose type is to be returned.
+     * @return {@link CommentType} instance for the given comment.
+     */
     private static CommentType getCommentType(String comment) {
         CommentType result = CommentType.UNKNOWN;
         final Matcher multilevelMatch = MULTILEVEL_COMMENT_REGEX.matcher(comment);
@@ -201,6 +264,13 @@ private static CommentType getCommentType(String comment) {
         return result;
     }
 
+    /**
+     * Returns starting position of a Line.
+     *
+     * @param line the line whose starting position is required.
+     * @param tabWidth tab width (passed value is 4 to this method).
+     * @return starting position of given line.
+     */
     private static int getLineStart(String line, final int tabWidth) {
         int lineStart = 0;
         for (int index = 0; index < line.length(); ++index) {

src/it/java/org/checkstyle/base/AbstractItModuleTestSupport.java

@@ -80,8 +80,8 @@ public enum ModuleCreationOption {
     /**
      * Find the module creation option to use for the module name.
      *
-     * @param moduleName The module name.
-     * @return The module creation option.
+     * @param moduleName the module name.
+     * @return the module creation option.
      */
     protected abstract ModuleCreationOption findModuleCreationOption(String moduleName);
 
@@ -276,7 +276,7 @@ protected final void verify(Checker checker,
      * Gets the check message 'as is' from appropriate 'messages.properties'
      * file.
      *
-     * @param aClass The package the message is located in.
+     * @param aClass the package the message is located in.
      * @param messageKey the key of message in 'messages.properties' file.
      * @param arguments  the arguments of message in 'messages.properties' file.
      * @return The message of the check with the arguments applied.
@@ -294,7 +294,7 @@ protected static String getCheckMessage(Class<? extends AbstractViolationReporte
     /**
      * Gets the check message 'as is' from appropriate 'messages.properties' file.
      *
-     * @param messages The map of messages to scan.
+     * @param messages the map of messages to scan.
      * @param messageKey the key of message in 'messages.properties' file.
      * @param arguments the arguments of message in 'messages.properties' file.
      * @return The message of the check with the arguments applied.

src/it/java/org/checkstyle/suppressionxpathfilter/AbstractXpathTestSupport.java

@@ -58,6 +58,11 @@ public abstract class AbstractXpathTestSupport extends AbstractCheckstyleModuleT
     @TempDir
     public Path temporaryFolder;
 
+    /**
+     * Returns name of the check.
+     *
+     * @return name of the check as a String.
+     */
     protected abstract String getCheckName();
 
     @Override
@@ -67,6 +72,14 @@ protected String getPackageLocation() {
         return "org/checkstyle/suppressionxpathfilter/" + subpackage;
     }
 
+    /**
+     * Returns a list of XPath queries to locate the violation nodes in a Java file.
+     *
+     * @param fileToProcess the Java file to be processed. {@link File} type object.
+     * @param position the position of violation in the file. {@link ViolationPosition} object.
+     * @return a list of strings containing XPath queries for locating violation nodes.
+     * @throws Exception can throw exceptions while accessing file contents.
+     */
     private static List<String> generateXpathQueries(File fileToProcess,
                                                      ViolationPosition position)
             throws Exception {
@@ -81,12 +94,28 @@ private static List<String> generateXpathQueries(File fileToProcess,
         return queryGenerator.generate();
     }
 
+    /**
+     * Verify generated XPath queries by comparing with expected queries.
+     *
+     * @param generatedXpathQueries a list of generated XPath queries.
+     * @param expectedXpathQueries a list of expected XPath queries.
+     */
     private static void verifyXpathQueries(List<String> generatedXpathQueries,
                                            List<String> expectedXpathQueries) {
         assertEquals(expectedXpathQueries,
                 generatedXpathQueries, "Generated queries do not match expected ones");
     }
 
+    /**
+     * Returns the path to the generated Suppressions XPath config file.
+     * This method creates a Suppressions config file containing the Xpath queries for
+     * any check and returns the path to that file.
+     *
+     * @param checkName the name of the check that is run.
+     * @param xpathQueries a list of generated XPath queries for violations in a file.
+     * @return path(String) to the generated Suppressions config file.
+     * @throws Exception can throw exceptions when writing/creating the config file.
+     */
     private String createSuppressionsXpathConfigFile(String checkName,
                                                      List<String> xpathQueries)
             throws Exception {
@@ -114,6 +143,14 @@ private String createSuppressionsXpathConfigFile(String checkName,
         return suppressionsXpathConfigPath.toString();
     }
 
+    /**
+     * Returns the config {@link DefaultConfiguration} for the created Suppression XPath filter.
+     *
+     * @param checkName the name of the check that is run.
+     * @param xpathQueries a list of generated XPath queries for violations in a file.
+     * @return the default config for Suppressions XPath filter based on check and xpath queries.
+     * @throws Exception can throw exceptions when creating config.
+     */
     private DefaultConfiguration createSuppressionXpathFilter(String checkName,
                                            List<String> xpathQueries) throws Exception {
         final DefaultConfiguration suppressionXpathFilterConfig =
@@ -124,6 +161,12 @@ private DefaultConfiguration createSuppressionXpathFilter(String checkName,
         return suppressionXpathFilterConfig;
     }
 
+    /**
+     * Extract line no and column nos from String of expected violations.
+     *
+     * @param expectedViolations the expected violations generated for the check.
+     * @return instance of type {@link ViolationPosition} which contains the line and column nos.
+     */
     private static ViolationPosition extractLineAndColumnNumber(String... expectedViolations) {
         ViolationPosition violation = null;
         final Matcher matcher =
@@ -176,6 +219,12 @@ private static final class ViolationPosition {
         private final int violationLineNumber;
         private final int violationColumnNumber;
 
+        /**
+         * Constructor of the class.
+         *
+         * @param violationLineNumber line no of the violation produced for the check.
+         * @param violationColumnNumber column no of the violation produced for the check.
+         */
         /* package */ ViolationPosition(int violationLineNumber,
                               int violationColumnNumber) {
             this.violationLineNumber = violationLineNumber;

src/test/java/com/puppycrawl/tools/checkstyle/AbstractModuleTestSupport.java

@@ -90,6 +90,13 @@ public final BriefUtLogger getBriefUtLogger() {
         return new BriefUtLogger(stream);
     }
 
+    /**
+     * Creates a default module configuration {@link DefaultConfiguration} for a given object
+     * of type {@link Class}.
+     *
+     * @param clazz a {@link Class} type object.
+     * @return default module configuration for the given {@link Class} instance.
+     */
     protected static DefaultConfiguration createModuleConfig(Class<?> clazz) {
         return new DefaultConfiguration(clazz.getName());
     }
@@ -214,6 +221,16 @@ protected final String getUriString(String filename) {
                 .toString();
     }
 
+    /**
+     * Performs verification of the file with the given file path using specified configuration
+     * and the array of expected messages. Also performs verification of the config with filters
+     * specified in the input file.
+     *
+     * @param filePath file path to verify.
+     * @param expectedUnfiltered an array of expected unfiltered config.
+     * @param expectedFiltered an array of expected config with filters.
+     * @throws Exception if exception occurs during verification process.
+     */
     protected final void verifyFilterWithInlineConfigParser(String filePath,
                                                             String[] expectedUnfiltered,
                                                             String... expectedFiltered)
@@ -427,6 +444,15 @@ private List<String> getActualViolationsForFile(Configuration config,
         return actualViolations.getOrDefault(file, new ArrayList<>());
     }
 
+    /**
+     * Returns the actual violations for each file that has been checked against {@link Checker}.
+     * Each file is mapped to their corresponding violation messages. Reads input stream for these
+     * messages using instance of {@link InputStreamReader}.
+     *
+     * @param errorCount count of errors after checking set of files against {@link Checker}.
+     * @return a {@link Map} object containing file names and the corresponding violation messages.
+     * @throws IOException exception can occur when reading input stream.
+     */
     private Map<String, List<String>> getActualViolations(int errorCount) throws IOException {
         // process each of the lines
         try (ByteArrayInputStream inputStream =
@@ -502,11 +528,22 @@ private static String internalGetCheckMessage(
         return formatter.format(arguments);
     }
 
+    /**
+     * Returns message bundle for a class specified by its class name.
+     *
+     * @return a string of message bundles for the class using class name.
+     */
     private String getMessageBundle() {
         final String className = getClass().getName();
         return getMessageBundle(className);
     }
 
+    /**
+     * Returns message bundles for a class by providing class name.
+     *
+     * @param className name of the class.
+     * @return message bundles containing package name.
+     */
     private static String getMessageBundle(String className) {
         final String messageBundle;
         final String messages = "messages";

src/test/java/com/puppycrawl/tools/checkstyle/AbstractPathTestSupport.java

@@ -67,6 +67,12 @@ protected final String getPath(String filename) throws IOException {
                 + filename).getCanonicalPath();
     }
 
+    /**
+     * Returns the path for resources for the given file name.
+     *
+     * @param filename name of the file.
+     * @return the path for resources for the given file based on its package location.
+     */
     protected final String getResourcePath(String filename) {
         return "/" + getPackageLocation() + "/" + filename;
     }
@@ -93,6 +99,13 @@ public static String addEndOfLine(String... strings) {
         return Stream.of(strings).collect(Collectors.joining(EOL, "", EOL));
     }
 
+    /**
+     * Returns a string containing "\r\n" converted to "\n" and "\\r\\n" converted to "\\n"
+     * by replacing with empty string.
+     *
+     * @param text the text string.
+     * @return the converted text string.
+     */
     protected static String toLfLineEnding(String text) {
         return text.replaceAll(CR_FOLLOWED_BY_LF_REGEX, "");
     }