Skip to content

[doc] Generate property override examples in rule doc #1714

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

Merged
merged 3 commits into from
Mar 19, 2019
Merged

[doc] Generate property override examples in rule doc #1714

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b126bf9
[doc] Generate property override examples in rule doc
adangel Mar 9, 2019
054b400
Filter out deprecated properties
oowekyala Mar 10, 2019
c716464
Fix tests
oowekyala Mar 10, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions pmd-core/src/main/java/net/sourceforge/pmd/lang/rule/stat/StatisticalRule.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,13 +29,15 @@ public interface StatisticalRule extends Rule {

/** @deprecated Not useful, will not be replaced. */
@Deprecated
DoubleProperty SIGMA_DESCRIPTOR = new DoubleProperty("sigma", "Sigma value", -10000000d, 1000000d, null, 1.0f);
DoubleProperty SIGMA_DESCRIPTOR = new DoubleProperty("sigma", "deprecated! Sigma value", -10000000d, 1000000d, null,
1.0f);
// TODO we should have one such property descriptor pro rule, and *not* share it, to allow setting specific defaults
DoubleProperty MINIMUM_DESCRIPTOR = new DoubleProperty("minimum", "Minimum reporting threshold", -10000000d, 1000000000d, null,
2.0f);
/** @deprecated Not useful, will not be replaced. */
@Deprecated
IntegerProperty TOP_SCORE_DESCRIPTOR = new IntegerProperty("topscore", "Top score value", 1, 100, null, 3.0f);
IntegerProperty TOP_SCORE_DESCRIPTOR = new IntegerProperty("topscore", "deprecated! Top score value", 1, 100,
null, 3.0f);

void addDataPoint(DataPoint point);

Expand Down
75 changes: 54 additions & 21 deletions pmd-doc/src/main/java/net/sourceforge/pmd/docs/RuleDocGenerator.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -442,29 +442,12 @@ private void generateRuleSetIndex(Map<Language, List<RuleSet>> rulesets) throws
lines.add("|----|-------------|-----------|-----------|");
for (PropertyDescriptor<?> propertyDescriptor : properties) {
String description = propertyDescriptor.description();
boolean isDeprecated = false;
if (description != null && description.toLowerCase(Locale.ROOT)
.startsWith(DEPRECATED_RULE_PROPERTY_MARKER)) {
isDeprecated = true;
final boolean isDeprecated = isDeprecated(propertyDescriptor);
if (isDeprecated) {
description = description.substring(DEPRECATED_RULE_PROPERTY_MARKER.length());
}

String defaultValue = "";
if (propertyDescriptor.defaultValue() != null) {
if (propertyDescriptor.isMultiValue()) {
@SuppressWarnings("unchecked") // multi valued properties are using a List
MultiValuePropertyDescriptor<List<?>> multiPropertyDescriptor = (MultiValuePropertyDescriptor<List<?>>) propertyDescriptor;
defaultValue = multiPropertyDescriptor.asDelimitedString(multiPropertyDescriptor.defaultValue());

// surround the delimiter with spaces, so that the browser can wrap
// the value nicely
defaultValue = defaultValue.replaceAll(Pattern.quote(
String.valueOf(multiPropertyDescriptor.multiValueDelimiter())),
" " + multiPropertyDescriptor.multiValueDelimiter() + " ");
} else {
defaultValue = String.valueOf(propertyDescriptor.defaultValue());
}
}
String defaultValue = determineDefaultValueAsString(propertyDescriptor, rule, true);

String multiValued = "no";
if (propertyDescriptor.isMultiValue()) {
Expand All @@ -483,11 +466,33 @@ private void generateRuleSetIndex(Map<Language, List<RuleSet>> rulesets) throws
lines.add("");
}

lines.add("**Use this rule by referencing it:**");
if (properties.isEmpty()) {
lines.add("**Use this rule by referencing it:**");
} else {
lines.add("**Use this rule with the default properties by just referencing it:**");
}
lines.add("``` xml");
lines.add("<rule ref=\"category/" + languageTersename + "/" + rulesetFilename + ".xml/" + rule.getName() + "\" />");
lines.add("```");
lines.add("");

if (properties.stream().anyMatch(it -> !isDeprecated(it))) {
lines.add("**Use this rule and customize it:**");
lines.add("``` xml");
lines.add("<rule ref=\"category/" + languageTersename + "/" + rulesetFilename + ".xml/" + rule.getName() + "\">");
lines.add(" <properties>");
for (PropertyDescriptor<?> propertyDescriptor : properties) {
if (!isDeprecated(propertyDescriptor)) {
String defaultValue = determineDefaultValueAsString(propertyDescriptor, rule, false);
lines.add(" <property name=\"" + propertyDescriptor.name() + "\" value=\""
+ defaultValue + "\" />");
}
}
lines.add(" </properties>");
lines.add("</rule>");
lines.add("```");
lines.add("");
}
}

writer.write(path, lines);
Expand All @@ -496,6 +501,34 @@ private void generateRuleSetIndex(Map<Language, List<RuleSet>> rulesets) throws
}
}

private static boolean isDeprecated(PropertyDescriptor<?> propertyDescriptor) {
return propertyDescriptor.description() != null
&& propertyDescriptor.description().toLowerCase(Locale.ROOT).startsWith(DEPRECATED_RULE_PROPERTY_MARKER);
}

private String determineDefaultValueAsString(PropertyDescriptor<?> propertyDescriptor, Rule rule, boolean pad) {
String defaultValue = "";
Object realDefaultValue = rule.getProperty(propertyDescriptor);
@SuppressWarnings("unchecked") // just force it, we know it's the right type
PropertyDescriptor<Object> captured = (PropertyDescriptor<Object>) propertyDescriptor;

if (realDefaultValue != null) {
defaultValue = captured.asDelimitedString(realDefaultValue);

if (pad && propertyDescriptor.isMultiValue()) {
@SuppressWarnings("unchecked") // multi valued properties are using a List
MultiValuePropertyDescriptor<List<?>> multiPropertyDescriptor = (MultiValuePropertyDescriptor<List<?>>) propertyDescriptor;

// surround the delimiter with spaces, so that the browser can wrap
// the value nicely
defaultValue = defaultValue.replaceAll(Pattern.quote(
String.valueOf(multiPropertyDescriptor.multiValueDelimiter())),
" " + multiPropertyDescriptor.multiValueDelimiter() + " ");
}
}
return defaultValue;
}

private static String stripIndentation(String description) {
if (description == null || description.isEmpty()) {
return "";
Expand Down
51 changes: 48 additions & 3 deletions pmd-doc/src/test/resources/expected/sample.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -76,11 +76,28 @@ public class JumbledIncrementerRule1 {
|sampleRegexProperty6|\\b|The property is of type regex|no|
|sampleRegexProperty7|\\n|The property is of type regex|no|

**Use this rule by referencing it:**
**Use this rule with the default properties by just referencing it:**
``` xml
<rule ref="category/java/sample.xml/JumbledIncrementer" />
```

**Use this rule and customize it:**
``` xml
<rule ref="category/java/sample.xml/JumbledIncrementer">
<properties>
<property name="sampleAdditionalProperty" value="the value" />
<property name="sampleMultiStringProperty" value="Value1|Value2" />
<property name="sampleRegexProperty1" value="\/\*\s+(default|package)\s+\*\/" />
<property name="sampleRegexProperty2" value="[a-z]*" />
<property name="sampleRegexProperty3" value="\s+" />
<property name="sampleRegexProperty4" value="_dd_" />
<property name="sampleRegexProperty5" value="[0-9]{1,3}" />
<property name="sampleRegexProperty6" value="\b" />
<property name="sampleRegexProperty7" value="\n" />
</properties>
</rule>
```

## MovedRule

<span style="border-radius: 0.25em; color: #fff; padding: 0.2em 0.6em 0.3em; display: inline; background-color: #d9534f;">Deprecated</span>
Expand Down Expand Up @@ -223,11 +240,28 @@ public class JumbledIncrementerRule1 {
|sampleRegexProperty6|\\b|The property is of type regex|no|
|sampleRegexProperty7|\\n|The property is of type regex|no|

**Use this rule by referencing it:**
**Use this rule with the default properties by just referencing it:**
``` xml
<rule ref="category/java/sample.xml/RenamedRule" />
```

**Use this rule and customize it:**
``` xml
<rule ref="category/java/sample.xml/RenamedRule">
<properties>
<property name="sampleAdditionalProperty" value="the value" />
<property name="sampleMultiStringProperty" value="Value1|Value2" />
<property name="sampleRegexProperty1" value="\/\*\s+(default|package)\s+\*\/" />
<property name="sampleRegexProperty2" value="[a-z]*" />
<property name="sampleRegexProperty3" value="\s+" />
<property name="sampleRegexProperty4" value="_dd_" />
<property name="sampleRegexProperty5" value="[0-9]{1,3}" />
<property name="sampleRegexProperty6" value="\b" />
<property name="sampleRegexProperty7" value="\n" />
</properties>
</rule>
```

## XSSInDocumentation

**Since:** PMD 0.1
Expand Down Expand Up @@ -296,7 +330,18 @@ public class Bar {
|XSSpropertyTest &lt;script&gt;alert('XSS');&lt;/script&gt;|&lt;script&gt;alert('XSS');&lt;/script&gt;|&lt;script&gt;alert('XSS');&lt;/script&gt;|no|
|escapingNeeded|this is escaped: \||You should be able to use \| in the description|no|

**Use this rule by referencing it:**
**Use this rule with the default properties by just referencing it:**
``` xml
<rule ref="category/java/sample.xml/XSSInDocumentation" />
```

**Use this rule and customize it:**
``` xml
<rule ref="category/java/sample.xml/XSSInDocumentation">
<properties>
<property name="sampleRegexProperty" value="\/\*\s+(default|package)\s+\*\/" />
<property name="XSSpropertyTest <script>alert('XSS');</script>" value="<script>alert('XSS');</script>" />
<property name="escapingNeeded" value="this is escaped: |" />
</properties>
</rule>
```