Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Issue #14759: Enhanced cmdline options documentation by tabular format #14799

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Issue #14759: Enhanced cmdline options documentation by tabular format #14799

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
3 changes: 2 additions & 1 deletion src/test/java/com/puppycrawl/tools/checkstyle/internal/CliOptionsXdocsSyncTest.java
View file
Open in desktop
Expand Up @@ -49,7 +49,8 @@ public void validateCliDocSections() throws Exception {
final Map<String, String> cmdDesc = new HashMap<>();

final NodeList sections = getSectionsFromXdoc("src/xdocs/cmdline.xml.vm");
final Set<String> cmdOptions = getListById(sections.item(2), "CLI_Options");
final Set<String> cmdOptions =
getListById(sections.item(2), "Command_line_usage_Command_line_options");
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What is 2 here?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nrmancuso , 2 is the section index of the XML (considering 0-based), I believe.

  1. Content
  2. Description
  3. Command Line Usage

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nrmancuso , could you please assign this PR to yourself.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nrmancuso , could you please assign this PR to yourself.

No need to assign reviewers until CI is green. CI is the first reviewer :)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need to assign reviewers until CI is green. CI is the first reviewer :)

Got it @nrmancuso , please see #14799 (comment).

I seem to be falling short on what I'm missing while debug 😕
Theoretically, the siblings are read only after firstChild is mapped and so on, but not sure why this (-c) is being skipped and continued to next node.

Copy link
Member

@romani romani May 11, 2024 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR changes xml a lot, but test that does selection from this xml is not changed. getListById should be changed a bit.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It use to be:

<ul id="CLI_Options">
        <li>
          <code>-c

Becomes a way more complicated and different:

....
<tbody>
              <tr>
                <td>
                  <a name="c"/>
                  <a href="#c">
                    <strong>-c</strong> configurationFile
                  </a>

So getListById should be rewritten.
@MANISH-K-07 , do need help to write a code?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will look into it at the earliest @romani

for (String option : cmdOptions) {
final String text = option.trim().replaceAll("\\s+", " ");
cmdDesc.put(text.substring(0, 2), text.substring(text.indexOf(" - ") + 3));
Expand Down
339 changes: 246 additions & 93 deletions src/xdocs/cmdline.xml.vm
View file
Open in desktop
Expand Up @@ -49,99 +49,252 @@ java -D&lt;property&gt;=&lt;value&gt; \
checks to apply. Command line options are:
</p>

<ul id="CLI_Options">
<li>
<code>-c configurationFile</code> - Specifies the location of the
file that defines the configuration modules. The location can either
be a filesystem location, or a
<a href=
"https://docs.oracle.com/javase/8/docs/technotes/guides/lang/resources.html#res_names">
name</a>
passed to the ClassLoader.getResource() method.
</li>
<li>
<code>-f format</code> - Specifies the output
format. Valid values: <code>xml</code>, <code>sarif</code>, <code>plain</code> for <a
href="apidocs/com/puppycrawl/tools/checkstyle/XMLLogger.html">XMLLogger</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/SarifLogger.html">SarifLogger</a>, and
<a href="apidocs/com/puppycrawl/tools/checkstyle/DefaultLogger.html">DefaultLogger</a>
respectively. Defaults to <code>plain</code>.
</li>
<li>
<code>-p propertiesFile</code> - Sets the property files to load.
</li>
<li>
<code>-o file</code> - Sets the output file. Defaults to stdout.
</li>
<li>
<code>-s line:column</code> - Prints xpath suppressions at the file's line and column
position.
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.
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.
</li>
<li>
<code>-g,--generate-xpath-suppression</code> - 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 <code>-c</code> option. Output location can be specified with <code>-o</code> option.
</li>
<li>
<code>-w, --tabWidth length</code> - Sets the length of the tab character. Used only with
<code>-s</code> option. Default value is 8.
</li>
<li>
<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> - 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> - 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> - 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.
</li>
<li>
<code>-e, --exclude excludedPath</code> - Directory/file to exclude from
CheckStyle. The path can be the full, absolute path, or relative to the current path.
Multiple excludes are allowed.
</li>
<li>
<code>-x, --exclude-regexp excludedPathPattern</code> - Directory/file pattern to
exclude from CheckStyle. Multiple excludes are allowed.
</li>
<li>
<code>-V, --version</code> - print product version and exit. Any other option is ignored.
</li>
<li>
<code>-b, --branch-matching-xpath xpathQuery</code>
- Shows Abstract Syntax Tree(AST) branches that match given XPath query.
</li>
<li>
<code>-h, --help</code> - print usage help message and exit. Any other option is ignored.
</li>
<li>
<code>-E, --executeIgnoredModules</code> - Allows ignored modules to be run.
</li>
</ul>
<subsection name="Command line options" id="Command_line_usage_Command_line_options">
<div class="wrapper">
<table>
<thead>
<tr>
<th>Option</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>
<a name="c"/>
<a href="#c">
<strong>-c</strong> configurationFile
</a>
</td>
<td>
Specifies the location of the file that defines the configuration modules.
The location can either be a filesystem location, or a
<a href="https://docs.oracle.com/javase/8/docs/technotes/guides/lang/resources.html#res_names">
name</a> passed to the ClassLoader.getResource() method.
</td>
</tr>
<tr>
<td>
<a name="f"/>
<a href="#f">
<strong>-f</strong> format
</a>
</td>
<td>
Specifies the output format. Valid values: <code>xml</code>,
<code>sarif</code>, <code>plain</code>
for <a href="apidocs/com/puppycrawl/tools/checkstyle/XMLLogger.html">
XMLLogger</a>,
<a href="apidocs/com/puppycrawl/tools/checkstyle/SarifLogger.html">
SarifLogger</a>, and
<a href="apidocs/com/puppycrawl/tools/checkstyle/DefaultLogger.html">
DefaultLogger</a> respectively. Defaults to <code>plain</code>.
</td>
</tr>
<tr>
<td>
<a name="p"/>
<a href="#p">
<strong>-p</strong> propertiesFile
</a>
</td>
<td>
Sets the property files to load.
</td>
</tr>
<tr>
<td>
<a name="o"/>
<a href="#o">
<strong>-o</strong> file
</a>
</td>
<td>
Sets the output file. Defaults to stdout.
</td>
</tr>
<tr>
<td>
<a name="s"/>
<a href="#s">
<strong>-s</strong> line:column
</a>
</td>
<td>
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.
</td>
</tr>
<tr>
<td>
<a name="g"/>
<a href="#g">
<strong>-g</strong>, --generate-xpath-suppression
</a>
</td>
<td>
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
<code>-c</code> option. Output location can be specified
with <code>-o</code> option.
</td>
</tr>
<tr>
<td>
<a name="w"/>
<a href="#w">
<strong>-w</strong>, --tabWidth length
</a>
</td>
<td>
Sets the length of the tab character. Used only with <code>-s</code> option.
Default value is 8.
</td>
</tr>
<tr>
<td>
<a name="t"/>
<a href="#t">
<strong>-t</strong>, --tree
</a>
</td>
<td>
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.
</td>
</tr>
<tr>
<td>
<a name="T"/>
<a href="#T">
<strong>-T</strong>, --treeWithComments
</a>
</td>
<td>
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.
</td>
</tr>
<tr>
<td>
<a name="J"/>
<a href="#J">
<strong>-J</strong>, --treeWithJavadoc
</a>
</td>
<td>
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. 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.
</td>
</tr>
<tr>
<td>
<a name="j"/>
<a href="#j">
<strong>-j</strong>, --javadocTree
</a>
</td>
<td>
This option is used to print the Parse Tree of the Javadoc comment. The file has
to contain <b>only Javadoc comment content</b> 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.
</td>
</tr>
<tr>
<td>
<a name="d"/>
<a href="#d">
<strong>-d</strong>, --debug
</a>
</td>
<td>
Prints all debug logging of CheckStyle utility.
</td>
</tr>
<tr>
<td>
<a name="e"/>
<a href="#e">
<strong>-e</strong>, --exclude excludedPath
</a>
</td>
<td>
Directory/file to exclude from Checkstyle. The path can be the full,
absolute path, or relative to the current path. Multiple excludes are allowed.
</td>
</tr>
<tr>
<td>
<a name="x"/>
<a href="#x">
<strong>-x</strong>, --exclude-regexp excludedPathPattern
</a>
</td>
<td>
Directory/file pattern to exclude from Checkstyle. Multiple excludes are allowed.
</td>
</tr>
<tr>
<td>
<a name="V"/>
<a href="#V">
<strong>-V</strong>, --version
</a>
</td>
<td>
Prints product version and exits. Any other option is ignored.
</td>
</tr>
<tr>
<td>
<a name="b"/>
<a href="#b">
<strong>-b</strong>, --branch-matching-xpath xpathQuery
</a>
</td>
<td>
Shows Abstract Syntax Tree(AST) branches that match given XPath query.
</td>
</tr>
<tr>
<td>
<a name="h"/>
<a href="#h">
<strong>-h</strong>, --help
</a>
</td>
<td>
Prints usage help message and exits. Any other option is ignored.
</td>
</tr>
<tr>
<td>
<a name="E"/>
<a href="#E">
<strong>-E</strong>, --executeIgnoredModules
</a>
</td>
<td>
Allows ignored modules to be run.
</td>
</tr>
</tbody>
</table>
</div>
</subsection>

<p>
Note that the <code>-n packageNamesFile</code>
Expand Down