From 9796faf26731e0903a19112ce4353794ca8f5918 Mon Sep 17 00:00:00 2001 From: MANISH-K-07 Date: Tue, 16 Apr 2024 12:33:34 +0100 Subject: [PATCH] Issue #14759: Enhanced cmdline options documentation by tabular format --- .../internal/CliOptionsXdocsSyncTest.java | 3 +- src/xdocs/cmdline.xml.vm | 331 +++++++++++++----- 2 files changed, 240 insertions(+), 94 deletions(-) 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..a477bfe5075 100644 --- a/src/test/java/com/puppycrawl/tools/checkstyle/internal/CliOptionsXdocsSyncTest.java +++ b/src/test/java/com/puppycrawl/tools/checkstyle/internal/CliOptionsXdocsSyncTest.java @@ -49,7 +49,8 @@ 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"); + final Set cmdOptions = + getListById(sections.item(2), "Command_line_usage_Command_line_options"); for (String option : cmdOptions) { final String text = option.trim().replaceAll("\\s+", " "); cmdDesc.put(text.substring(0, 2), text.substring(text.indexOf(" - ") + 3)); diff --git a/src/xdocs/cmdline.xml.vm b/src/xdocs/cmdline.xml.vm index 9df28354fb6..4a094464450 100644 --- a/src/xdocs/cmdline.xml.vm +++ b/src/xdocs/cmdline.xml.vm @@ -49,99 +49,244 @@ 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. Note that the column + numbers between the 2 will not be in sync with the file's numbering due to the + fact that each javadoc comment is parsed separately from the java file. +
+ + + -j, --javadocTree + + + This option is used to print the Parse Tree of the Javadoc comment. The file has + to contain only Javadoc comment content without including '/**' 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