From b126bf94d2ccf42850d5b465e6fbc5be7ad38604 Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Sat, 9 Mar 2019 16:21:11 +0100 Subject: [PATCH 1/3] [doc] Generate property override examples in rule doc Refs #1712 --- .../pmd/docs/RuleDocGenerator.java | 58 +++++++++++++------ pmd-doc/src/test/resources/expected/sample.md | 53 ++++++++++++++++- 2 files changed, 91 insertions(+), 20 deletions(-) diff --git a/pmd-doc/src/main/java/net/sourceforge/pmd/docs/RuleDocGenerator.java b/pmd-doc/src/main/java/net/sourceforge/pmd/docs/RuleDocGenerator.java index 3c5fdb049e..a30b5cfa2c 100644 --- a/pmd-doc/src/main/java/net/sourceforge/pmd/docs/RuleDocGenerator.java +++ b/pmd-doc/src/main/java/net/sourceforge/pmd/docs/RuleDocGenerator.java @@ -449,22 +449,7 @@ public class RuleDocGenerator { 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> multiPropertyDescriptor = (MultiValuePropertyDescriptor>) 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); String multiValued = "no"; if (propertyDescriptor.isMultiValue()) { @@ -483,11 +468,30 @@ public class RuleDocGenerator { 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(""); lines.add("```"); lines.add(""); + + if (!properties.isEmpty()) { + lines.add("**Use this rule and customize it:**"); + lines.add("``` xml"); + lines.add(""); + lines.add(" "); + for (PropertyDescriptor propertyDescriptor : properties) { + String defaultValue = determineDefaultValueAsString(propertyDescriptor); + lines.add(" "); + } + lines.add(" "); + lines.add(""); + lines.add("```"); + lines.add(""); + } } writer.write(path, lines); @@ -496,6 +500,26 @@ public class RuleDocGenerator { } } + private String determineDefaultValueAsString(PropertyDescriptor propertyDescriptor) { + String defaultValue = ""; + if (propertyDescriptor.defaultValue() != null) { + if (propertyDescriptor.isMultiValue()) { + @SuppressWarnings("unchecked") // multi valued properties are using a List + MultiValuePropertyDescriptor> multiPropertyDescriptor = (MultiValuePropertyDescriptor>) 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()); + } + } + return defaultValue; + } + private static String stripIndentation(String description) { if (description == null || description.isEmpty()) { return ""; diff --git a/pmd-doc/src/test/resources/expected/sample.md b/pmd-doc/src/test/resources/expected/sample.md index b5c5d9a145..eb55f991d0 100644 --- a/pmd-doc/src/test/resources/expected/sample.md +++ b/pmd-doc/src/test/resources/expected/sample.md @@ -76,11 +76,29 @@ 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 ``` +**Use this rule and customize it:** +``` xml + + + + + + + + + + + + + + +``` + ## MovedRule Deprecated @@ -223,11 +241,29 @@ 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 ``` +**Use this rule and customize it:** +``` xml + + + + + + + + + + + + + + +``` + ## XSSInDocumentation **Since:** PMD 0.1 @@ -296,7 +332,18 @@ public class Bar { |XSSpropertyTest <script>alert('XSS');</script>|<script>alert('XSS');</script>|<script>alert('XSS');</script>|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 ``` + +**Use this rule and customize it:** +``` xml + + + + + + + +``` From 054b4003fd544c62b9dfcb7045ba47ca64b45e21 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Fournier?= Date: Sun, 10 Mar 2019 16:39:37 +0100 Subject: [PATCH 2/3] Filter out deprecated properties Also: * Suppress space padding for xml default values * Fetch default value from the rule --- .../pmd/lang/rule/stat/StatisticalRule.java | 6 ++- .../pmd/docs/RuleDocGenerator.java | 37 ++++++++++++------- 2 files changed, 27 insertions(+), 16 deletions(-) diff --git a/pmd-core/src/main/java/net/sourceforge/pmd/lang/rule/stat/StatisticalRule.java b/pmd-core/src/main/java/net/sourceforge/pmd/lang/rule/stat/StatisticalRule.java index 1bb01ec055..2796454383 100644 --- a/pmd-core/src/main/java/net/sourceforge/pmd/lang/rule/stat/StatisticalRule.java +++ b/pmd-core/src/main/java/net/sourceforge/pmd/lang/rule/stat/StatisticalRule.java @@ -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); diff --git a/pmd-doc/src/main/java/net/sourceforge/pmd/docs/RuleDocGenerator.java b/pmd-doc/src/main/java/net/sourceforge/pmd/docs/RuleDocGenerator.java index a30b5cfa2c..acf13282e6 100644 --- a/pmd-doc/src/main/java/net/sourceforge/pmd/docs/RuleDocGenerator.java +++ b/pmd-doc/src/main/java/net/sourceforge/pmd/docs/RuleDocGenerator.java @@ -442,14 +442,12 @@ public class RuleDocGenerator { 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 = determineDefaultValueAsString(propertyDescriptor); + String defaultValue = determineDefaultValueAsString(propertyDescriptor, rule, true); String multiValued = "no"; if (propertyDescriptor.isMultiValue()) { @@ -478,14 +476,17 @@ public class RuleDocGenerator { lines.add("```"); lines.add(""); - if (!properties.isEmpty()) { + if (properties.stream().anyMatch(it -> !isDeprecated(it))) { lines.add("**Use this rule and customize it:**"); lines.add("``` xml"); lines.add(""); lines.add(" "); for (PropertyDescriptor propertyDescriptor : properties) { - String defaultValue = determineDefaultValueAsString(propertyDescriptor); - lines.add(" "); + if (!isDeprecated(propertyDescriptor)) { + String defaultValue = determineDefaultValueAsString(propertyDescriptor, rule, false); + lines.add(" "); + } } lines.add(" "); lines.add(""); @@ -500,21 +501,29 @@ public class RuleDocGenerator { } } - private String determineDefaultValueAsString(PropertyDescriptor propertyDescriptor) { + 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 = ""; - if (propertyDescriptor.defaultValue() != null) { - if (propertyDescriptor.isMultiValue()) { + Object realDefaultValue = rule.getProperty(propertyDescriptor); + @SuppressWarnings("unchecked") // just force it, we know it's the right type + PropertyDescriptor captured = (PropertyDescriptor) propertyDescriptor; + + if (realDefaultValue != null) { + defaultValue = captured.asDelimitedString(realDefaultValue); + + if (pad && propertyDescriptor.isMultiValue()) { @SuppressWarnings("unchecked") // multi valued properties are using a List MultiValuePropertyDescriptor> multiPropertyDescriptor = (MultiValuePropertyDescriptor>) 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()); } } return defaultValue; From c71646475d45b3cd349e67e6791fd14b60f2bded Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Fournier?= Date: Sun, 10 Mar 2019 17:21:28 +0100 Subject: [PATCH 3/3] Fix tests --- pmd-doc/src/test/resources/expected/sample.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/pmd-doc/src/test/resources/expected/sample.md b/pmd-doc/src/test/resources/expected/sample.md index eb55f991d0..866bb6815c 100644 --- a/pmd-doc/src/test/resources/expected/sample.md +++ b/pmd-doc/src/test/resources/expected/sample.md @@ -86,8 +86,7 @@ public class JumbledIncrementerRule1 { - - + @@ -251,8 +250,7 @@ public class JumbledIncrementerRule1 { - - +