From efbe149f21d52c49bd498d5bdeed9fefff71b3a8 Mon Sep 17 00:00:00 2001
From: Scott Wells <scott@illuminatedcloud.com>
Date: Wed, 20 Oct 2021 11:42:52 -0500
Subject: [PATCH] Issue 3566 - Added a new configuration property,
 'reportMissingDescription', that if set to false (default is true if
 unspecified) doesn't report an issue if the '@description' tag is missing.
 This is consistent with the dialect supported by ApexDoc derivatives such as
 SfApexDoc.

---
 .../apex/rule/documentation/ApexDocRule.java  | 11 +++-
 .../resources/category/apex/documentation.xml |  2 +-
 .../apex/rule/documentation/xml/ApexDoc.xml   | 57 +++++++++++++++++++
 3 files changed, 66 insertions(+), 4 deletions(-)

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 441693eee0..13aecd1ff7 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
@@ -44,9 +44,14 @@ public class ApexDocRule extends AbstractApexRule {
             booleanProperty("reportProtected")
                 .desc("Report protected methods").defaultValue(false).build();
 
+    private static final PropertyDescriptor<Boolean> REPORT_MISSING_DESCRIPTION_DESCRIPTOR =
+            booleanProperty("reportMissingDescription")
+                .desc("Report missing @description").defaultValue(true).build();
+
     public ApexDocRule() {
         definePropertyDescriptor(REPORT_PRIVATE_DESCRIPTOR);
         definePropertyDescriptor(REPORT_PROTECTED_DESCRIPTOR);
+        definePropertyDescriptor(REPORT_MISSING_DESCRIPTION_DESCRIPTOR);
 
         addRuleChainVisit(ASTUserClass.class);
         addRuleChainVisit(ASTUserInterface.class);
@@ -79,7 +84,7 @@ public class ApexDocRule extends AbstractApexRule {
                 addViolationWithMessage(data, node, MISSING_COMMENT_MESSAGE);
             }
         } else {
-            if (!comment.hasDescription) {
+            if (getProperty(REPORT_MISSING_DESCRIPTION_DESCRIPTOR) && !comment.hasDescription) {
                 addViolationWithMessage(data, node, MISSING_DESCRIPTION_MESSAGE);
             }
 
@@ -113,7 +118,7 @@ public class ApexDocRule extends AbstractApexRule {
                 addViolationWithMessage(data, node, MISSING_COMMENT_MESSAGE);
             }
         } else {
-            if (!comment.hasDescription) {
+            if (getProperty(REPORT_MISSING_DESCRIPTION_DESCRIPTOR) && !comment.hasDescription) {
                 addViolationWithMessage(data, node, MISSING_DESCRIPTION_MESSAGE);
             }
         }
@@ -128,7 +133,7 @@ public class ApexDocRule extends AbstractApexRule {
                 addViolationWithMessage(data, node, MISSING_COMMENT_MESSAGE);
             }
         } else {
-            if (!comment.hasDescription) {
+            if (getProperty(REPORT_MISSING_DESCRIPTION_DESCRIPTOR) && !comment.hasDescription) {
                 addViolationWithMessage(data, node, MISSING_DESCRIPTION_MESSAGE);
             }
         }
diff --git a/pmd-apex/src/main/resources/category/apex/documentation.xml b/pmd-apex/src/main/resources/category/apex/documentation.xml
index 5699ab1dff..de9ffc875a 100644
--- a/pmd-apex/src/main/resources/category/apex/documentation.xml
+++ b/pmd-apex/src/main/resources/category/apex/documentation.xml
@@ -22,7 +22,7 @@ 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.
+*   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
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 0bd349a322..76a010069f 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
@@ -571,6 +571,63 @@ public class Foo {
 
     public class Bar {
     }
+}
+        ]]></code>
+    </test-code>
+
+    <test-code>
+        <description>#3566 [apex] ApexDoc: Verify use of reportMissingDescription, negative test unspecified/default</description>
+        <!-- reportMissingDescription unspecified; should default to true -->
+        <expected-problems>2</expected-problems>
+        <code><![CDATA[
+/**
+ * No at-description tag provided.
+ */
+public class Foo {
+
+    /**
+     * No at-description tag provided.
+     */
+    public Foo() {
+    }
+}
+        ]]></code>
+    </test-code>
+
+    <test-code>
+        <description>#3566 [apex] ApexDoc: Verify use of reportMissingDescription, negative test specified</description>
+        <rule-property name="reportMissingDescription">true</rule-property>
+        <expected-problems>2</expected-problems>
+        <code><![CDATA[
+/**
+ * No at-description tag provided.
+ */
+public class Foo {
+
+    /**
+     * No at-description tag provided.
+     */
+    public Foo() {
+    }
+}
+        ]]></code>
+    </test-code>
+
+    <test-code>
+        <description>#3566 [apex] ApexDoc: Verify use of reportMissingDescription, positive test</description>
+        <rule-property name="reportMissingDescription">false</rule-property>
+        <expected-problems>0</expected-problems>
+        <code><![CDATA[
+/**
+ * No at-description tag provided.
+ */
+public class Foo {
+
+    /**
+     * No at-description tag provided.
+     */
+    public Foo() {
+    }
 }
         ]]></code>
     </test-code>