Skip to content

Commit

Permalink
doc: updated cmdline docs to be more specific
Browse files Browse the repository at this point in the history
  • Loading branch information
@MANISH-K-07 @rnveach
MANISH-K-07 authored and rnveach committed Apr 16, 2024
1 parent 85987c3 commit b1498c3
Show file tree
Hide file tree
Showing 3 changed files with 57 additions and 63 deletions.
33 changes: 15 additions & 18 deletions src/main/java/com/puppycrawl/tools/checkstyle/Main.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -680,7 +680,7 @@ private static final class CliOptions {
+ "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. ATTENTION: generated result will have few queries, joined "
+ "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 "
Expand Down Expand Up @@ -723,35 +723,32 @@ private static final class CliOptions {

/** Option that controls whether to print the AST of the file. */
@Option(names = {"-t", "--tree"},
description = "Prints Abstract Syntax Tree(AST) of the checked file. The option "
+ "cannot be used other options and requires exactly one file to run on "
+ "to be specified.")
description = "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.")
private boolean printAst;

/** Option that controls whether to print the AST of the file including comments. */
@Option(names = {"-T", "--treeWithComments"},
description = "Prints Abstract Syntax Tree(AST) with comment nodes "
+ "of the checked file. The option cannot be used with other options "
+ "and requires exactly one file to run on to be specified.")
description = "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.")
private boolean printAstWithComments;

/** Option that controls whether to print the parse tree of the javadoc comment. */
@Option(names = {"-j", "--javadocTree"},
description = "Prints Parse Tree of the Javadoc comment. "
+ "The file have to contain only Javadoc comment content without "
+ "including '/**' and '*/' at the beginning and at the end respectively. "
+ "The option cannot be used other options and requires exactly one file "
+ "to run on to be specified.")
description = "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.")
private boolean printJavadocTree;

/** Option that controls whether to print the full AST of the file. */
@Option(names = {"-J", "--treeWithJavadoc"},
description = "Prints Abstract Syntax Tree(AST) with Javadoc nodes "
+ "and comment nodes of the checked file. Attention that line number and "
+ "columns will not be the same as it is a file due to the fact that each "
+ "javadoc comment is parsed separately from java file. The option cannot "
+ "be used with other options and requires exactly one file to run on to "
+ "be specified.")
description = "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.")
private boolean printTreeWithJavadoc;

/** Option that controls whether to print debug info. */
Expand Down
58 changes: 28 additions & 30 deletions src/test/java/com/puppycrawl/tools/checkstyle/MainTest.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -119,24 +119,20 @@ public class MainTest {
+ " location can be%n"
+ " specified with -o option.%n"
+ " -h, --help Show this help message and exit.%n"
+ " -j, --javadocTree Prints Parse Tree of the Javadoc comment. The"
+ " file have to contain only%n"
+ " Javadoc comment content without including"
+ " '/**' and '*/' at the%n"
+ " beginning and at the end respectively. The"
+ " option cannot be used%n"
+ " other options and requires exactly one file"
+ " to run on to be specified.%n"
+ " -J, --treeWithJavadoc Prints Abstract Syntax Tree(AST) with Javadoc"
+ " nodes and comment nodes%n"
+ " of the checked file. Attention that line number"
+ " and columns will not%n"
+ " be the same as it is a file due to the fact"
+ " that each javadoc comment%n"
+ " is parsed separately from java file. The"
+ " option cannot be used with%n"
+ " other options and requires exactly one file to"
+ " run on to be specified.%n"
+ " -j, --javadocTree This option is used to print the Parse Tree of"
+ " the Javadoc comment. The%n"
+ " file has to contain only Javadoc comment"
+ " content excluding '/**' and%n"
+ " '*/' at the beginning and at the end"
+ " respectively. It can only be%n"
+ " used on a single file and cannot be"
+ " combined with other options.%n"
+ " -J, --treeWithJavadoc This option is used to display the Abstract"
+ " Syntax Tree (AST) with%n"
+ " Javadoc nodes of the specified file. It can"
+ " only be used on a single%n"
+ " file and cannot be combined"
+ " with other options.%n"
+ " -o=<outputPath> Sets the output file. Defaults to stdout.%n"
+ " -p=<propertiesFile> Sets the property files to load.%n"
+ " -s=<suppressionLineColumnNumber>%n"
Expand All @@ -148,8 +144,8 @@ public class MainTest {
+ " for. The option cannot%n"
+ " be used with other options and requires exactly"
+ " one file to run on to%n"
+ " be specified. ATTENTION: generated result will"
+ " have few queries,%n"
+ " be specified. Note that the generated result"
+ " will have few queries,%n"
+ " joined by pipe(|). Together they will match all"
+ " AST nodes on%n"
+ " specified line and column. You need to choose"
Expand All @@ -158,16 +154,18 @@ public class MainTest {
+ " but might result in%n"
+ " undesirable matching and suppress other"
+ " issues.%n"
+ " -t, --tree Prints Abstract Syntax Tree(AST) of the checked"
+ " file. The option cannot%n"
+ " be used other options and requires exactly one"
+ " file to run on to be%n"
+ " specified.%n"
+ " -T, --treeWithComments Prints Abstract Syntax Tree(AST) with comment"
+ " nodes of the checked%n"
+ " file. The option cannot be used with other"
+ " options and requires%n"
+ " exactly one file to run on to be specified.%n"
+ " -t, --tree This option is used to display the Abstract"
+ " Syntax Tree (AST) without%n"
+ " any comments of the specified file. It can"
+ " only be used on a single%n"
+ " file and cannot be combined with"
+ " other options.%n"
+ " -T, --treeWithComments This option is used to display the Abstract"
+ " Syntax Tree (AST) with%n"
+ " comment nodes excluding Javadoc of the"
+ " specified file. It can only be%n"
+ " used on a single file and cannot be combined"
+ " with other options.%n"
+ " -V, --version Print version information and exit.%n"
+ " -w, --tabWidth=<tabWidth> Sets the length of the tab character. Used only"
+ " with -s option. Default%n"
Expand Down
29 changes: 14 additions & 15 deletions src/xdocs/cmdline.xml.vm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ java -D&lt;property&gt;=&lt;value&gt; \
Argument is the line and column number (separated by a <code>:</code> ) 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.
ATTENTION: generated result will have few queries, joined by pipe(<code>|</code>).
Note that the generated result will have few queries, joined by pipe(<code>|</code>).
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.
Expand All @@ -96,26 +96,25 @@ java -D&lt;property&gt;=&lt;value&gt; \
<code>-s</code> option. Default value is 8.
</li>
<li>
<code>-t, --tree</code> - Prints Abstract Syntax Tree(AST) of the checked file. The option
cannot be used other options and requires exactly one file to run on to be specified.
<code>-t, --tree</code> - This option is used to display the Abstract Syntax Tree (AST)
<b>without any comments</b> of the specified file. It can only be used on a single file
and cannot be combined with other options.
</li>
<li>
<code>-T, --treeWithComments</code> - Prints Abstract Syntax Tree(AST) with comment nodes
of the checked file. The option cannot be used with other options and requires exactly
one file to run on to be specified.
<code>-T, --treeWithComments</code> - This option is used to display the Abstract Syntax
Tree (AST) <b>with comment nodes excluding Javadoc</b> of the specified file. It can only
be used on a single file and cannot be combined with other options.
</li>
<li>
<code>-J, --treeWithJavadoc</code> - Prints Abstract Syntax Tree(AST) with Javadoc nodes
and comment nodes of the checked file. Attention that line number and columns will not be
the same as it is a file due to the fact that each javadoc comment is parsed separately
from java file. The option cannot be used with other options and requires exactly one
file to run on to be specified.
<code>-J, --treeWithJavadoc</code> - This option is used to display the Abstract Syntax
Tree (AST) <b>with Javadoc nodes</b> of the specified file. It can only be used on a
single file and cannot be combined with other options.
</li>
<li>
<code>-j, --javadocTree</code> - Prints Parse Tree of the Javadoc comment.
The file have to contain <b>only Javadoc comment content</b> without including '/**' and
'*/' at the beginning and at the end respectively. The option
cannot be used other options and requires exactly one file to run on to be specified.
<code>-j, --javadocTree</code> - This option is used to print the Parse Tree of the
Javadoc comment. The file has to contain <b>only Javadoc comment content</b>
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.
</li>
<li>
<code>-d, --debug</code> - Prints all debug logging of CheckStyle utility.
Expand Down

0 comments on commit b1498c3

Please sign in to comment.