From de080f02e49a2daf41cdf49b084b85dc86aadc49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Fournier?= Date: Fri, 25 May 2018 03:02:37 +0200 Subject: [PATCH] Improve CLI reference --- docs/_includes/custom/cli_option_row.html | 23 ++ docs/_plugins/custom_filters.rb | 25 ++ docs/pages/pmd/userdocs/cli_reference.md | 286 ++++++++++------------ 3 files changed, 179 insertions(+), 155 deletions(-) create mode 100644 docs/_includes/custom/cli_option_row.html diff --git a/docs/_includes/custom/cli_option_row.html b/docs/_includes/custom/cli_option_row.html new file mode 100644 index 0000000000..e17fe362b4 --- /dev/null +++ b/docs/_includes/custom/cli_option_row.html @@ -0,0 +1,23 @@ + + + + + + + + + +{% assign arg = {{ include.option_arg | prepend: " <" | append: ">" | escape_once | keep_if: include.option_arg }} %} +{% capture required_label %}{% if include.required %}Required {% endif %}{% endcapture %} + + {{ include.options | split: ',' | mappend: arg | join: "
" }} + {{ required_label }} + {{ include.description + | regex_replace: "`(.*?)`", "\1" + | regex_replace: "\*\*(.*?)\*\*", "\1" + | regex_replace: "\*(.*?)\*", "\1" + | regex_replace: "\[(.*?)\]\((.*?)\)", "\1" }} + + {{ include.default }} + {{ include.languages }} + diff --git a/docs/_plugins/custom_filters.rb b/docs/_plugins/custom_filters.rb index 6013d57f86..bbd62f2aae 100644 --- a/docs/_plugins/custom_filters.rb +++ b/docs/_plugins/custom_filters.rb @@ -44,6 +44,31 @@ module CustomFilters end + def regex_replace(str, regex, subst) + if str && regex + str.gsub(Regexp::new(regex), subst || "") + end + end + + def regex_split(str, regex = nil) + if str + str.split(regex && Regexp::new(regex)) + end + end + + # Takes an array of strings and maps every element x to {{ x | append: suffix }} + def mappend(xs, suffix) + Array(xs).map {|x| "#{x}#{suffix}" } + end + + # Returns the initial argument only if the second argument is truthy + def keep_if(any, test) + if test + any + end + end + + private def flatten_rec(seq) diff --git a/docs/pages/pmd/userdocs/cli_reference.md b/docs/pages/pmd/userdocs/cli_reference.md index 0ea31bd17c..9b1eb1b76a 100644 --- a/docs/pages/pmd/userdocs/cli_reference.md +++ b/docs/pages/pmd/userdocs/cli_reference.md @@ -15,157 +15,130 @@ The tool comes with a rather extensive help text, simply running with `-help`! Option Description - Required - Applies for language + Default value + Applies to - - -rulesets / -R - Comma separated list of ruleset names to use - yes - - - - -dir / -d - Root directory for sources - yes - - - - -format / -f - Report format type. Default format is `text`. - no - - - - -auxclasspath - - Specifies the classpath for libraries used by the source code. This is used by the type resolution. - Alternatively a `file://` URL to a text file containing path elements on consecutive lines can be - specified. - - no - Java - - - -uri / -u - Database URI for sources. If this is given, then you don't need to provide `-dir`. - no - PLSQL - - - -filelist - Path to file containing a comma delimited list of files to analyze. If this is given, then you don't need to provide `-dir`. - no - - - - -debug / -verbose / -D / -V - Debug mode. Prints more log output. - no - - - - -help / -h / -H - Display help on usage. - no - - - - -encoding / -e - Specifies the character set encoding of the source code files PMD is reading (i.e. UTF-8). Default is `UTF-8`. - no - - - - -threads / -t - Sets the number of threads used by PMD. Default is `1`. Set threads to '0' to disable multi-threading processing. - no - - - - -benchmark / -b - Benchmark mode - output a benchmark report upon completion; defaults to System.err - no - - - - -stress / -S - Performs a stress test. - no - - - - -shortnames - Prints shortened filenames in the report. - no - - - - -showsuppressed - Report should show suppressed rule violations. - no - - - - -suppressmarker - Specifies the string that marks the line which PMD should ignore; default is `NOPMD`. - no - - - - -minimumpriority / -min - Rule priority threshold; rules with lower priority than configured here won't be used. Default is `5` - which is the lowest priority. - no - - - - -property / -P - `{name}={value}`: Define a property for a report format. - no - - - - -reportfile / -r - Send report output to a file; default to System.out - no - - - - -version / -v - Specify version of a language PMD should use. - no - - - - -language / -l - Specify a language PMD should use. - no - - - - -failOnViolation {true|false} - By default PMD exits with status 4 if violations are found. - Disable this option with '-failOnViolation false' to exit with 0 instead and just write the report. - - no - - - - -cache - Specify a location for the analysis cache file to use. - This can greatly improve analysis performance and is highly recommended. - no - - - - -no-cache - Explicitly disable incremental analysis. This switch turns off suggestions to use Incremental Analysis, - and causes the -cache option to be discarded if it is provided. - - - - + {% include custom/cli_option_row.html options="-rulesets,-R" + option_arg="refs" + description="Comma-separated list of ruleset or rule references." + required="yes" + %} + {% include custom/cli_option_row.html options="-dir,-d" + option_arg="path" + description="Root directory for the analyzed sources." + required="yes" + %} + {% include custom/cli_option_row.html options="-format,-f" + option_arg="format" + description="Output format of the analysis report. The available formats + are described [here](#available-report-formats)." + default="text" + %} + + {% include custom/cli_option_row.html options="-auxclasspath" + option_arg="cp" + description="Specifies the classpath for libraries used by the source code. + This is used by the type resolution. Alternatively a `file://` URL + to a text file containing path elements on consecutive lines can be specified." + languages="Java" + %} + {% include custom/cli_option_row.html options="-benchmark,-b" + description="Enables benchmark mode, which outputs a benchmark report upon completion. + The report is sent to standard error." + default="false" + %} + {% include custom/cli_option_row.html options="-cache" + option_arg="path" + description="Specifies a location for the analysis cache file to use. + This can greatly improve analysis performance and is **highly recommended**." + %} + {% include custom/cli_option_row.html options="-debug,-verbose,-D,-V" + description="Debug mode. Prints more log output." + default="false" + %} + {% include custom/cli_option_row.html options="-encoding,-e" + option_arg="charset" + description="Specifies the character set encoding of the source code files PMD is reading. + The valid values are the standard character sets of `java.nio.charset.Charset`." + default="UTF-8" + %} + {% include custom/cli_option_row.html options="-failOnViolation,--failOnViolation" + option_arg="bool" + description="Specifies whether PMD exits with non-zero status if violations are found. + By default PMD exits with status 4 if violations are found. + Disable this feature with `-failOnViolation false` to exit with 0 instead and just output the report." + default="true" + %} + {% include custom/cli_option_row.html options="-filelist" + option_arg="files" + description="Path to file containing a comma delimited list of files to analyze. + If this is given, then you don't need to provide `-dir`." + %} + {% include custom/cli_option_row.html options="-help,-h,-H" + description="Display help on usage." + default="false" + %} + {% include custom/cli_option_row.html options="-language,-l" + option_arg="lang" + description="Specify the language PMD should use." + %} + {% include custom/cli_option_row.html options="-minimumpriority,-min" + option_arg="num" + description="Rule priority threshold; rules with lower priority than configured here won't be used." + default="5" + %} + {% include custom/cli_option_row.html options="-norulesetcompatibility" + description='Disables the ruleset compatibility filter. The filter is active by default and tries to automatically "fix" old ruleset files with old rule names' + default="false" + %} + {% include custom/cli_option_row.html options="-no-cache" + description="Explicitly disables incremental analysis. This switch turns off suggestions to use Incremental Analysis, + and causes the `-cache` option to be discarded if it is provided." + default="false" + %} + {% include custom/cli_option_row.html options="-property,-P" + option_arg="name>= ## Exit Status @@ -174,8 +147,8 @@ This behavior has been introduced to ease PMD integration into scripts or hooks, - - + +
0Everything is fine, no violations found
1Couldn't understand command line parameters or PMD exited with an exception
4At least one violation has been detected, unless '-failOnViolation false' is set.
1Couldn't understand command-line parameters or PMD exited with an exception
4At least one violation has been detected, unless -failOnViolation false is set.
@@ -191,9 +164,12 @@ This behavior has been introduced to ease PMD integration into scripts or hooks, * [xml and xsl](/pmd_rules_xml.html) -## Available Report Formats / Renderers +## Available Report Formats -PMD comes with many different renderer types: +PMD comes with many different renderers. +The mnemonics in bold are used to select them on the command line, as +arguments to the `-format` option. Some formats accept *properties*, +which can be specified with the `-property` option on the command-line. * **codeclimate**: Renderer for Code Climate JSON format. @@ -223,7 +199,7 @@ PMD comes with many different renderer types: Properties: - * classAndMethodName: Class and method name, pass '.method' when processing a directory. + * classAndMethodName: Class and method name, pass `.method` when processing a directory. * sourcePath: * fileName: @@ -240,7 +216,7 @@ PMD comes with many different renderer types: Properties: - * color: Enables colors with anything other than 'false' or '0'. Default: yes. + * color: Enables colors with anything other than `false` or `0`. Default: yes. * **textpad**: TextPad integration.