Merge pull request from babula:master

[apex] ApexDoc: Add reportProperty property #3693

* pr-3693:
  [doc] Update release notes (#3693)
  [apex] ApexDoc - handle properties via "reportProperty".
  Add reportMissingProperty property

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 %}
 

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<Boolean> 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<Boolean> 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<Boolean> REPORT_MISSING_DESCRIPTION_DESCRIPTOR =
             booleanProperty("reportMissingDescription")
                 .desc("Report missing @description").defaultValue(true).build();
 
+    private static final PropertyDescriptor<Boolean> 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;
     }
 

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.
         </description>

pmd-apex/src/test/resources/net/sourceforge/pmd/lang/apex/rule/documentation/xml/ApexDoc.xml

@@ -628,6 +628,53 @@ public class Foo {
      */
     public Foo() {
     }
+}
+        ]]></code>
+    </test-code>
+
+    <test-code>
+        <description>property should have comment</description>
+        <rule-property name="reportProperty">true</rule-property>
+        <expected-problems>1</expected-problems>
+        <expected-linenumbers>5</expected-linenumbers>
+        <code><![CDATA[
+/**
+ * @description Foo
+ */
+public class Foo {
+    global Object Bar { get; set; }
+}
+        ]]></code>
+    </test-code>
+
+    <test-code>
+        <description>property with missing description</description>
+        <rule-property name="reportProperty">false</rule-property>
+        <expected-problems>1</expected-problems>
+        <expected-linenumbers>8</expected-linenumbers>
+        <code><![CDATA[
+/**
+ * @description Foo
+ */
+public class Foo {
+    /**
+     * the property bar
+     */
+    global Object Bar { get; set; }
+}
+        ]]></code>
+    </test-code>
+
+    <test-code>
+        <description>property does not need comment</description>
+        <rule-property name="reportProperty">false</rule-property>
+        <expected-problems>0</expected-problems>
+        <code><![CDATA[
+/**
+ * @description Foo
+ */
+public class Foo {
+    global Object Bar { get; set; }
 }
         ]]></code>
     </test-code>