diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/internal/CliOptionsXdocsSyncTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/internal/CliOptionsXdocsSyncTest.java index c75f439a6ac..9e644214938 100644 --- a/src/test/java/com/puppycrawl/tools/checkstyle/internal/CliOptionsXdocsSyncTest.java +++ b/src/test/java/com/puppycrawl/tools/checkstyle/internal/CliOptionsXdocsSyncTest.java @@ -24,6 +24,7 @@ import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; +import java.util.ArrayList; import java.util.HashMap; import java.util.HashSet; import java.util.List; @@ -46,14 +47,9 @@ public class CliOptionsXdocsSyncTest { @Test public void validateCliDocSections() throws Exception { - final Map cmdDesc = new HashMap<>(); - final NodeList sections = getSectionsFromXdoc("src/xdocs/cmdline.xml.vm"); - final Set cmdOptions = getListById(sections.item(2), "CLI_Options"); - for (String option : cmdOptions) { - final String text = option.trim().replaceAll("\\s+", " "); - cmdDesc.put(text.substring(0, 2), text.substring(text.indexOf(" - ") + 3)); - } + final Node cmdUsageSection = sections.item(2); + final Map cmdOptions = getOptions(cmdUsageSection); final Class cliOptions = Class.forName("com.puppycrawl.tools.checkstyle" + ".Main$CliOptions"); @@ -63,10 +59,10 @@ public void validateCliDocSections() throws Exception { for (OptionSpec opt : optionSpecList) { final String option = opt.names()[0]; if ("-h".equals(option) || "-V".equals(option)) { - cmdDesc.remove(option); + cmdOptions.remove(option); continue; } - final String descXdoc = cmdDesc.get(option); + final String descXdoc = cmdOptions.get(option); final String descMain = opt.description()[0]; assertWithMessage("CLI Option: " + option + " present in " + "Main.java but not documented in cmdline.xml.vm") @@ -74,13 +70,13 @@ public void validateCliDocSections() throws Exception { .isNotNull(); assertWithMessage("CLI options descriptions in xdoc: " + " should match that of in Main.java") - .that(descMain) - .isEqualTo(descXdoc); - cmdDesc.remove(option); + .that(descMain) + .isEqualTo(descXdoc); + cmdOptions.remove(option); } assertWithMessage("CLI Options: %s present in cmdline.xml.vm, not documented in Main.java", - cmdDesc) - .that(cmdDesc) + cmdOptions) + .that(cmdOptions) .isEmpty(); } @@ -133,14 +129,26 @@ private static NodeList getSectionsFromXdoc(String xdocPath) throws Exception { return document.getElementsByTagName("section"); } - private static Set getListById(Node subSection, String id) { - Set result = null; - final Node node = XmlUtil.findChildElementById(subSection, id); - if (node != null) { - result = XmlUtil.getChildrenElements(node) - .stream() - .map(Node::getTextContent) - .collect(Collectors.toUnmodifiableSet()); + private static Map getOptions(Node subSection) { + final Map result = new HashMap<>(); + final Node subsectionNode = XmlUtil.findChildElementById(subSection, + "Command_line_usage_Command_Line_Options"); + if (subsectionNode != null) { + final Node divNode = XmlUtil.getFirstChildElement(subsectionNode); + final Node tableNode = XmlUtil.getFirstChildElement(divNode); + final Node tbodyNode = XmlUtil.findChildElementById(tableNode, "body"); + final Set rows = XmlUtil.findChildElementsByTag(tbodyNode, "tr"); + final List> columns = rows.stream() + .map(row -> new ArrayList<>(XmlUtil.getChildrenElements(row))) + .collect(Collectors.toUnmodifiableList()); + for (List column : columns) { + final Node command = column.get(1); + final Node description = column.get(2); + if (command != null && description != null) { + result.put(command.getTextContent().trim().substring(0, 2), + description.getTextContent().trim().replaceAll("\\s+", " ")); + } + } } return result; } diff --git a/src/xdocs/cmdline.xml.vm b/src/xdocs/cmdline.xml.vm index acf0fe876c0..45069dd56dd 100644 --- a/src/xdocs/cmdline.xml.vm +++ b/src/xdocs/cmdline.xml.vm @@ -49,99 +49,341 @@ java -D<property>=<value> \ checks to apply. Command line options are:

-
    -
  • - -c configurationFile - Specifies the location of the - file that defines the configuration modules. The location can either - be a filesystem location, or a - - name - passed to the ClassLoader.getResource() method. -
    • -
  • - -f format - Specifies the output - format. Valid values: xml, sarif, plain for XMLLogger, - SarifLogger, and - DefaultLogger - respectively. Defaults to plain. -
    • -
  • - -p propertiesFile - Sets the property files to load. -
    • -
  • - -o file - Sets the output file. Defaults to stdout. -
    • -
  • - -s line:column - Prints xpath suppressions at the file's line and column - position. - Argument is the line and column number (separated by a : ) in the file - that the suppression should be generated for. The option cannot be used - with other options and requires exactly one file to run on to be specified. - Note that the generated result will have few queries, joined by pipe(|). - Together they will match all AST nodes on specified line - and column. You need to choose only one and recheck that it works. Usage of all of them is - also ok, but might result in undesirable matching and suppress other issues. -
    • -
  • - -g,--generate-xpath-suppression - Generates to output a suppression xml - to use to suppress all violations from user's config. Instead of printing every violation, - all violations will be catched and single suppressions xml file will be printed out. - Used only - with -c option. Output location can be specified with -o option. -
    • -
  • - -w, --tabWidth length - Sets the length of the tab character. Used only with - -s option. Default value is 8. -
    • -
  • - -t, --tree - This option is used to display the Abstract Syntax Tree (AST) - without any comments of the specified file. It can only be used on a single file - and cannot be combined with other options. -
    • -
  • - -T, --treeWithComments - This option is used to display the Abstract Syntax - Tree (AST) with comment nodes excluding Javadoc of the specified file. It can only - be used on a single file and cannot be combined with other options. -
    • -
  • - -J, --treeWithJavadoc - This option is used to display the Abstract Syntax - Tree (AST) with Javadoc nodes of the specified file. It can only be used on a - single file and cannot be combined with other options. -
    • -
  • - -j, --javadocTree - This option is used to print the Parse Tree of the - Javadoc comment. The file has to contain only Javadoc comment content - excluding '/**' and '*/' at the beginning and at the end respectively. It can only be - used on a single file and cannot be combined with other options. -
    • -
  • - -d, --debug - Prints all debug logging of CheckStyle utility. -
    • -
  • - -e, --exclude excludedPath - Directory/file to exclude from - CheckStyle. The path can be the full, absolute path, or relative to the current path. - Multiple excludes are allowed. -
    • -
  • - -x, --exclude-regexp excludedPathPattern - Directory/file pattern to - exclude from CheckStyle. Multiple excludes are allowed. -
    • -
  • - -V, --version - print product version and exit. Any other option is ignored. -
    • -
  • - -b, --branch-matching-xpath xpathQuery - - Shows Abstract Syntax Tree(AST) branches that match given XPath query. -
    • -
  • - -h, --help - print usage help message and exit. Any other option is ignored. -
    • -
  • - -E, --executeIgnoredModules - Allows ignored modules to be run. -
    • -
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ OptionDescription
+ + + + + + + + -c configurationFile + + Specifies the location of the file that defines the configuration modules. + The location can either be a filesystem location, or a + + name passed to the ClassLoader.getResource() method. +
+ + + + + + + + -f format + + Specifies the output format. Valid values: xml, + sarif, plain + for + XMLLogger, + + SarifLogger, and + + DefaultLogger respectively. Defaults to plain. +
+ + + + + + + + -p propertiesFile + + Sets the property files to load. +
+ + + + + + + + -o file + + Sets the output file. Defaults to stdout. +
+ + + + + + + + -s line:column + + Prints xpath suppressions at the file's line and column position. Argument is the + line and column number (separated by a : ) in the file that the suppression + should be generated for. The option cannot be used with other options and + requires exactly one file to run on to be specified. Note that the generated + result will have few queries, joined by pipe(|). Together they will match all + AST nodes on specified line and column. You need to choose only one and recheck + that it works. Usage of all of them is also ok, but might result in undesirable + matching and suppress other issues. +
+ + + + + + + + -g--generate-xpath-suppression + + Generates to output a suppression xml to use to suppress all violations from + user's config. Instead of printing every violation, all violations will be + catched and single suppressions xml file will be printed out. Used only with + -c option. Output location can be specified + with -o option. +
+ + + + + + + + -w, --tabWidth length + + Sets the length of the tab character. Used only with -s option. + Default value is 8. +
+ + + + + + + + -t, --tree + + This option is used to display the Abstract Syntax Tree + (AST) without any comments of the specified file. It can only be used + on a single file and cannot be combined with other options. +
+ + + + + + + + -T, --treeWithComments + + This option is used to display the Abstract Syntax Tree + (AST) with comment nodes excluding Javadoc of the specified file. + It can only be used on a single file and cannot be combined with other options. +
+ + + + + + + + -J, --treeWithJavadoc + + This option is used to display the Abstract Syntax Tree + (AST) with Javadoc nodes of the specified file. It can only be used on + a single file and cannot be combined with other options. +
+ + + + + + + + -j, --javadocTree + + This option is used to print the Parse Tree of the Javadoc comment. The file has + to contain only Javadoc comment content excluding '/**' and '*/' + at the beginning and at the end respectively. It can only be used on a + single file and cannot be combined with other options. +
+ + + + + + + + -d, --debug + + Prints all debug logging of CheckStyle utility. +
+ + + + + + + + -e, --exclude excludedPath + + Directory/file to exclude from CheckStyle. The path can be the full, + absolute path, or relative to the current path. Multiple excludes are allowed. +
+ + + + + + + + -x, --exclude-regexp excludedPathPattern + + Directory/file pattern to exclude from CheckStyle. Multiple excludes are allowed. +
+ + + + + + + + -V, --version + + Prints product version and exits. Any other option is ignored. +
+ + + + + + + + -b, --branch-matching-xpath xpathQuery + + Shows Abstract Syntax Tree(AST) branches that match given XPath query. +
+ + + + + + + + -h, --help + + Prints usage help message and exits. Any other option is ignored. +
+ + + + + + + + -E, --executeIgnoredModules + + Allows ignored modules to be run. +
+
+

Note that the -n packageNamesFile