hiifong/pmd
1
0
Fork 0
forked from phoedos/pmd
Code Pull Requests Activity

You should transform "using rule properties" to a whole "configuring rules" page

Browse Source
This commit is contained in:
Clément Fournier 2018-05-21 01:02:58 +02:00
parent 8f43350b64
commit 29e4ce1314
5 changed files with 63 additions and 105 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/_data/sidebars/pmd_sidebar.yml
View File

@ -34,17 +34,14 @@ entries:
- title: Installation and basic CLI usage
url: /pmd_userdocs_installation.html
output: web, pdf
- title: Full CLI reference
url: /pmd_userdocs_cli_reference.html
output: web, pdf
- title: Understanding rulesets
url: /pmd_userdocs_understanding_rulesets.html
output: web, pdf
- title: Making rulesets
url: /pmd_userdocs_making_rulesets.html
output: web, pdf
- title: Using rule properties
url: /pmd_userdocs_using_properties.html
- title: Configuring rules
url: /pmd_userdocs_configuring_rules.html
output: web, pdf
- title: Best practices
url: /pmd_userdocs_best_practices.html
@ -52,6 +49,9 @@ entries:
- title: Suppressing warnings
url: /pmd_userdocs_suppressing_warnings.html
output: web, pdf
- title: PMD CLI reference
url: /pmd_userdocs_cli_reference.html
output: web, pdf
- title: null
output: web, pdf
subfolders:

103
docs/index.md
View File

@ -1,7 +1,6 @@
---
title: PMD Documentation website
keywords: java
tags: []
permalink: index.html
toc: false
summary: >
@ -17,96 +16,28 @@ author: Jeff Jensen <jjensen@apache.org>, Andreas Dangel <andreas.dangel@adangel
First time user? Then you may be interested in our [quickstart page](TODO).
<br/>
<div id="grid" class="row">
{% include custom/shuffle_panel.html
tag="essentials"
description="These pages summarize the Gist of PMD usage to get you started quickly:"
title="Essential resources" %}
<div class="row">
<div class="col-lg-12">
<h2 class="page-header">Quick access</h2>
</div>
<div class="col-md-3 col-sm-6">
<div class="panel panel-default text-center">
<div class="panel-heading">
<span class="fa-stack fa-5x">
<i class="fa fa-circle fa-stack-2x text-primary"></i>
<i class="fa fa-paper-plane fa-stack-1x fa-inverse"></i>
</span>
</div>
<div class="panel-body">
<h4>Getting started</h4>
<p>A collection of pages explaining the gist of PMD <b>usage</b> and <b>ruleset making</b>.</p>
<a href="tag_getting_started.html" class="btn btn-primary">Learn More</a>
</div>
</div>
</div>
<div class="col-md-3 col-sm-6">
<div class="panel panel-default text-center">
<div class="panel-heading">
<span class="fa-stack fa-5x">
<i class="fa fa-circle fa-stack-2x text-primary"></i>
<i class="fa fa-expand fa-stack-1x fa-inverse"></i>
</span>
</div>
<div class="panel-body">
<h4>Extending PMD</h4>
<p>Guides about <b>writing rules</b>, metrics, and testing them properly.</p>
<a href="tag_navigation.html" class="btn btn-primary">Learn More</a>
</div>
</div>
</div>
<div class="col-md-3 col-sm-6">
<div class="panel panel-default text-center">
<div class="panel-heading">
<span class="fa-stack fa-5x">
<i class="fa fa-circle fa-stack-2x text-primary"></i>
<i class="fa fa-list fa-stack-1x fa-inverse"></i>
</span>
</div>
<div class="panel-body">
<h4>Rule reference</h4>
<p>Find an <b>existing rule</b> to craft your own rulesets.</p>
<a href="tag_single_sourcing.html" class="btn btn-primary">Learn More</a>
</div>
</div>
</div>
<div class="col-md-3 col-sm-6">
<div class="panel panel-default text-center">
<div class="panel-heading">
<span class="fa-stack fa-5x">
<i class="fa fa-circle fa-stack-2x text-primary"></i>
<i class="fa fa-code-fork fa-stack-1x fa-inverse"></i>
</span>
</div>
<div class="panel-body">
<h4>Contributing</h4>
<p>Help us make PMD better!</p>
<a href="tag_formatting.html" class="btn btn-primary">Learn More</a>
</div>
</div>
</div>
{% include custom/shuffle_panel.html
tag="rule_references"
title="Rule references"
description="Pick your language to find out about the rule it supports:"
image="fa-database"
titlemaker="page.language_name" %}
{% include custom/shuffle_panel_filler.html %}
</div>
# More details
{% include custom/shuffle_panel.html
tag="essentials"
description="These pages summarize the Gist of PMD usage to get you started quickly:"
title="Essential resources" %}
{% include custom/shuffle_panel.html
tag="rule_references"
title="Rule references"
description="Pick your language to find out about the rule it supports:"
image="fa-database"
titlemaker="page.language_name" %}
{% include custom/shuffle_panel_filler.html %}
<!-- {% include image.html file="pmd-logo-big.png" alt="PMD Logo" %} -->
{% include links.html %}

4
docs/pages/pmd/userdocs/cli_reference.md
View File

@ -1,6 +1,6 @@
---
title: Full CLI reference
summary: "Full reference for the command-line interface, including options, output formats and supported languages"
title: PMD CLI reference
summary: "Full reference for PMD's command-line interface, including options, output formats and supported languages"
tags: [essentials, userdocs]
permalink: pmd_userdocs_cli_reference.html
author: Tom Copeland <tom@infoether.com>, Xavier Le Vourch <xlv@users.sourceforge.net>, Juan Martín Sotuyo Dodero <juansotuyo@gmail.com>

40
docs/pages/pmd/userdocs/using_properties.md → docs/pages/pmd/userdocs/configuring_rules.md
View File

@ -1,13 +1,41 @@
---
title: Using rule properties
short_title: Using rule properties
tags: [customizing, properties]
summary: "Properties are a way to parameterise the behaviour of PMD rules and your own directly from the ruleset XML, which greatly improves their reusability. This page explains how to use rule properties to make the most of your rulesets."
last_updated: December 2017 (6.0.0)
permalink: pmd_userdocs_using_properties.html
title: Configuring rules
short_title: Configuring rules
keywords: [property, properties, message, priority]
tags: [customizing, userdocs, essentials]
summary: "Learn how to configure your rules directly from the ruleset XML."
last_updated: May 2018 (6.4.0)
permalink: pmd_userdocs_configuring_rules.html
author: Hooper Bloob <hooperbloob@users.sourceforge.net>, Romain Pelisse <rpelisse@users.sourceforge.net>, Clément Fournier <clement.fournier76@gmail.com>
---
## Message and priority overriding
You can change a rule's **message** by specifying a `message`
attribute on the rule element. This will override the previous
value and change the message the rule will print on the report.
Similarly, the **priority** of a rule can be changed via a nested
element. Using priority, you can deactivate some rules based on a
minimum priority threshold (set using the `-min` CLI option).
Priority is an integer ranging from 1 to 5, with 1 being the highest
priority.
Putting things together, the following rule reference lowers the priority
of EmptyCatchBlock to 5, such that e.g. using the `-min 4` CLI parameters
will cause the rule to be ignored.
```xml
<rule ref="category/java/errorprone.xml/EmptyCatchBlock"
message="Empty catch blocks should be avoided" >
<priority>5</priority>
</rule>
```
## Rule properties
Properties make it easy to customise the behaviour of a rule directly from the xml. They come in several types, which correspond to the type of their values. For example, NPathComplexity declares a property "reportLevel", with an integer value type, and which corresponds to the threshold above which a method will be reported. If you believe that its default value of 200 is too high, you could lower it to e.g. 150 in the following way:
```xml

11
docs/pages/pmd/userdocs/understanding_rulesets.md
View File

@ -1,9 +1,9 @@
---
title: Understanding Rulesets
tags: [rulesets]
tags: [essentials, userdocs]
permalink: pmd_userdocs_understanding_rulesets.html
summary: Rules belong to categories and rulesets are custom collections of rules
last_updated: November 2017
summary: "Learn how to specify which rules you want to run, and how, by creating your own rulesets."
last_updated: May 2018 (6.4.0)
---
@ -19,7 +19,7 @@ Rulesets are written in XML. The following sections walk you through the creatio
## Creating a custom ruleset
The first step is to create a new XML file. You can use the following template:
The first step is to create a new empty ruleset. You can use the following template:
``` xml
<?xml version="1.0"?>
@ -74,5 +74,4 @@ How to read the `ref` attribute?
### 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).
Main documentation page: [Configuring rules](pmd_userdocs_configuring_rules.html)