From 8f43350b648023e7409ad420334cb5d441067fc7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Fournier?= Date: Mon, 21 May 2018 00:48:41 +0200 Subject: [PATCH] Rewrite understanding_rulesets.md, needs merging with making_rulesets.md --- docs/pages/pmd/userdocs/installation.md | 13 +-- .../pmd/userdocs/understanding_rulesets.md | 99 ++++++++----------- 2 files changed, 48 insertions(+), 64 deletions(-) diff --git a/docs/pages/pmd/userdocs/installation.md b/docs/pages/pmd/userdocs/installation.md index 12bb81aa69..7393cf94a1 100644 --- a/docs/pages/pmd/userdocs/installation.md +++ b/docs/pages/pmd/userdocs/installation.md @@ -27,12 +27,13 @@ Unzip it into any directory, optionally add the `bin` subdirectory in your `PATH ## Running PMD via command line -{% include callout.html type="primary" content="PMD comes with several command line utilities, like CPD, the rule -designer or PMD itself. -On Unix, you can run any of them using the script `run.sh`, located inside the `bin/` directory of the PMD distribution -. The first argument is the name of the utility you want to execute ('pmd', 'designer', ...), e.g. PMD is launched via -`run.sh pmd`. The rest of the arguments are specific to the utility used.

-On Windows, each utility has its own startup script, e.g. `pmd.bat`, `cpd.bat`." %} +{% include callout.html type="primary" + content="PMD comes with several command line utilities, like CPD, the rule designer or PMD itself. + On Unix, you can run any of them using the script `run.sh`, located inside the `bin/` + directory of the PMD distribution. The first argument is the name of the utility you want + to execute ('pmd', 'designer', ...), e.g. PMD is launched via `run.sh pmd`. The rest of + the arguments are specific to the utility used.

+ On Windows, each utility has its own startup script, e.g. `pmd.bat`, `cpd.bat`." %} The PMD command (`pmd.bat` or `run.sh pmd`) requires three options: diff --git a/docs/pages/pmd/userdocs/understanding_rulesets.md b/docs/pages/pmd/userdocs/understanding_rulesets.md index 0492d6b483..f5cfe21d96 100644 --- a/docs/pages/pmd/userdocs/understanding_rulesets.md +++ b/docs/pages/pmd/userdocs/understanding_rulesets.md @@ -6,52 +6,20 @@ summary: Rules belong to categories and rulesets are custom collections of rules last_updated: November 2017 --- -## Rule Categories -Since PMD 6.0.0, all provided built-in rules are sorted into one of eight categories: +## What's a ruleset? -1. **Best Practices**: These are rules which enforce generally accepted best practices. -2. **Code Style**: These rules enforce a specific coding style. -3. **Design**: Rules that help you discover design issues. -4. **Documentation**: These rules are related to code documentation. -5. **Error Prone**: Rules to detect constructs that are either broken, extremely confusing or prone to runtime errors. -6. **Multithreading**: These are rules that flag issues when dealing with multiple threads of execution. -7. **Performance**: Rules that flag suboptimal code. -8. **Security**: Rules that flag potential security flaws. +A *ruleset* is a configuration file, which describes a collection of PMD *rules* to be executed +in a PMD run. PMD includes built-in rulesets to run quick analyses with a default configuration, but +users are encouraged to make their own rulesets from the start, because they allow for so much +configurability. -These categories help you to find rules and figure out the relevance and impact for your project. - -You can find the available rules under "Rule Reference" in the menu. Each languages has its own rule -index, e.g. [Java Rules](pmd_rules_java.html) or [JavaScript Rules](pmd_rules_ecmascript.html). - -{% include note.html content="Not all supported languages provide rules in all categories yet. " %} +Rulesets are written in XML. The following sections walk you through the creation of a ruleset. -## Rulesets +## Creating a custom ruleset -There are two major use cases: - -1. When defining a new rule, the rule needs to be defined in a ruleset. PMD's built-in rules - are defined in special rulesets which form the eight categories mentioned above. - From these rulesets the rule reference documentation is generated, - see [Java Rules](pmd_rules_java.html) for an example. - - Similar rules are grouped together into the same category, like [Java Best Practices](pmd_rules_java_bestpractices.html) - which contains rules which enforce generally accepted best practices. Each category uses its own - ruleset file. - -2. When executing PMD, you need to tell, which rules should be executed. You could directly point to the - built-in rulesets, but then you might be overwhelmed by the found violations. As described - in [Best Practices](pmd_userdocs_best_practices.html), it's better to define an own custom ruleset. - - With an own custom ruleset, you can: - - * Select the rules, that should be executed - * Adjust the rule properties to exactly meet your needs - -## Create a custom ruleset - -You start by creating a new XML file with the following contents: +The first step is to create a new XML file. You can use the following template: ``` xml @@ -60,36 +28,51 @@ You start by creating a new XML file with the following contents: xmlns="http://pmd.sourceforge.net/ruleset/2.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://pmd.sourceforge.net/ruleset/2.0.0 http://pmd.sourceforge.net/ruleset_2_0_0.xsd"> + -Custom rules + My custom rules + + + ``` -Now start to add rule by **referencing** them. Let's say, you want to start with finding -[Empty Catch Blocks](pmd_rules_java_errorprone.html#emptycatchblock). Then you'd add the following -rule reference inside the `ruleset` elements: +### Referencing rules + +To use the built-in rules PMD provides, you need to add some *references* to them. Here's a +basic rule reference: ```xml ``` -## Adjusting rule properties +Adding that element into the `ruleset` element adds the rule [EmptyCatchBlock](pmd_rules_java_errorprone.html#emptycatchblock) +to your ruleset. This is a Java rule, so it will be executed on every Java file PMD encounters in +its search space. -If you want to be less strict with empty catch blocks, you could define that an exception variable name -of `ignored` will not raise a violation. Therefore you would reference the rule **and** define -the appropriate property value: +How to read the `ref` attribute? -```xml - - - - ^ignored$ - - - -``` +* `category/java/errorprone.xml` is a reference to the Java category `errorprone`. Since PMD 6.0.0, + all PMD built-in rules are sorted in one of eight categories, which are consistent across languages: + + 1. **Best Practices**: These are rules which enforce generally accepted best practices.
+ 2. **Code Style**: These rules enforce a specific coding style.
+ 3. **Design**: Rules that help you discover design issues.
+ 4. **Documentation**: These rules are related to code documentation.
+ 5. **Error Prone**: Rules to detect constructs that are either broken, extremely confusing or prone to runtime errors.
+ 6. **Multithreading**: These are rules that flag issues when dealing with multiple threads of execution.
+ 7. **Performance**: Rules that flag suboptimal code.
+ 8. **Security**: Rules that flag potential security flaws." + +{% include tip.html content="You can discover the available rules by language and category [from this page](tag_rule_references.html)" %} -{% include note.html content="More information about rulesets can be found on [Making Rulesets](pmd_userdocs_making_rulesets.html)." %} +* `EmptyCatchBlock` is simply the name of the rule. If there were no rule with that name within the specified + category, then PMD would fail before starting the analysis. + +### Configuring individual rules + +Many rules give you some freedom of configuration by letting you use **rule properties**. +Configuring rules this way [is described on this page](pmd_userdocs_using_properties.html).