diff --git a/docs/pages/release_notes.md b/docs/pages/release_notes.md index 9f1e462e68..c194608353 100644 --- a/docs/pages/release_notes.md +++ b/docs/pages/release_notes.md @@ -14,6 +14,12 @@ This is a {{ site.pmd.release_type }} release. ### New and noteworthy +#### Modified rules + +* The Apex rule {% rule "apex/documentation/ApexDoc" %} has a new property `reportProperty`. + If set to `false` (default is `true` if unspecified) doesn't report missing ApexDoc comments on properties. + It allows you to enforce ApexDoc comments for classes and methods without requiring them for properties. + ### Fixed Issues * java-bestpractices @@ -29,6 +35,7 @@ This is a {{ site.pmd.release_type }} release. * [#3631](https://github.com/pmd/pmd/pull/3631): \[java] Fixed False positive for UselessStringValueOf when there is no initial String to append to - [John Armgardt](https://github.com/johnra2) * [#3683](https://github.com/pmd/pmd/pull/3683): \[java] Fixed 3468 UnusedPrivateMethod false positive when outer class calls private static method on inner class - [John Armgardt](https://github.com/johnra2) * [#3688](https://github.com/pmd/pmd/pull/3688): \[java] Bump log4j to 2.16.0 - [Sergey Nuyanzin](https://github.com/snuyanzin) +* [#3693](https://github.com/pmd/pmd/pull/3693): \[apex] ApexDoc: Add reportProperty property - [Steve Babula](https://github.com/babula) {% endtocmaker %} diff --git a/pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/rule/documentation/ApexDocRule.java b/pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/rule/documentation/ApexDocRule.java index 13aecd1ff7..be33bc1c04 100644 --- a/pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/rule/documentation/ApexDocRule.java +++ b/pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/rule/documentation/ApexDocRule.java @@ -38,20 +38,25 @@ public class ApexDocRule extends AbstractApexRule { private static final PropertyDescriptor REPORT_PRIVATE_DESCRIPTOR = booleanProperty("reportPrivate") - .desc("Report private classes and methods").defaultValue(false).build(); + .desc("Report private classes, methods and properties").defaultValue(false).build(); private static final PropertyDescriptor REPORT_PROTECTED_DESCRIPTOR = booleanProperty("reportProtected") - .desc("Report protected methods").defaultValue(false).build(); + .desc("Report protected classes, methods and properties").defaultValue(false).build(); private static final PropertyDescriptor REPORT_MISSING_DESCRIPTION_DESCRIPTOR = booleanProperty("reportMissingDescription") .desc("Report missing @description").defaultValue(true).build(); + private static final PropertyDescriptor REPORT_PROPERTY_DESCRIPTOR = + booleanProperty("reportProperty") + .desc("Report properties without comments").defaultValue(true).build(); + public ApexDocRule() { definePropertyDescriptor(REPORT_PRIVATE_DESCRIPTOR); definePropertyDescriptor(REPORT_PROTECTED_DESCRIPTOR); definePropertyDescriptor(REPORT_MISSING_DESCRIPTION_DESCRIPTOR); + definePropertyDescriptor(REPORT_PROPERTY_DESCRIPTOR); addRuleChainVisit(ASTUserClass.class); addRuleChainVisit(ASTUserInterface.class); @@ -113,6 +118,7 @@ public class ApexDocRule extends AbstractApexRule { @Override public Object visit(ASTProperty node, Object data) { ApexDocComment comment = getApexDocComment(node); + if (comment == null) { if (shouldHaveApexDocs(node)) { addViolationWithMessage(data, node, MISSING_COMMENT_MESSAGE); @@ -151,12 +157,18 @@ public class ApexDocRule extends AbstractApexRule { } } + // is it a property? + if (node instanceof ASTProperty && !getProperty(REPORT_PROPERTY_DESCRIPTOR)) { + return false; + } + ASTModifierNode modifier = node.getFirstChildOfType(ASTModifierNode.class); if (modifier != null) { boolean flagPrivate = getProperty(REPORT_PRIVATE_DESCRIPTOR) && modifier.isPrivate(); boolean flagProtected = getProperty(REPORT_PROTECTED_DESCRIPTOR) && modifier.isProtected(); return (modifier.isPublic() || modifier.isGlobal() || flagPrivate || flagProtected) && !modifier.isOverride(); } + return false; } diff --git a/pmd-apex/src/main/resources/category/apex/documentation.xml b/pmd-apex/src/main/resources/category/apex/documentation.xml index de9ffc875a..bbe588d08f 100644 --- a/pmd-apex/src/main/resources/category/apex/documentation.xml +++ b/pmd-apex/src/main/resources/category/apex/documentation.xml @@ -22,11 +22,13 @@ This rule validates that: overrides and test classes (as well as the contents of test classes). * ApexDoc comments are present for classes, methods, and properties that are protected or private, depending on the properties `reportPrivate` and `reportProtected`. -* ApexDoc comments should contain @description depending on the property 'reportMissingDescription'. +* ApexDoc comments should contain @description depending on the property `reportMissingDescription`. * ApexDoc comments on non-void, non-constructor methods should contain @return. * ApexDoc comments on void or constructor methods should not contain @return. * ApexDoc comments on methods with parameters should contain @param for each parameter, in the same order as the method signature. +* ApexDoc comments are present on properties is only validated, if the property `reportProperty` is enabled. + By setting `reportProperty` to false, you can ignore missing comments on properties. Method overrides and tests are both exempted from having ApexDoc. diff --git a/pmd-apex/src/test/resources/net/sourceforge/pmd/lang/apex/rule/documentation/xml/ApexDoc.xml b/pmd-apex/src/test/resources/net/sourceforge/pmd/lang/apex/rule/documentation/xml/ApexDoc.xml index 76a010069f..3f0bc23b07 100644 --- a/pmd-apex/src/test/resources/net/sourceforge/pmd/lang/apex/rule/documentation/xml/ApexDoc.xml +++ b/pmd-apex/src/test/resources/net/sourceforge/pmd/lang/apex/rule/documentation/xml/ApexDoc.xml @@ -628,6 +628,53 @@ public class Foo { */ public Foo() { } +} + ]]> + + + + property should have comment + true + 1 + 5 + + + + + property with missing description + false + 1 + 8 + + + + + property does not need comment + false + 0 +