From abfdb572d34512417028d3501bebcecab9b1cb13 Mon Sep 17 00:00:00 2001 From: babula Date: Fri, 17 Dec 2021 13:34:47 -0500 Subject: [PATCH 1/3] Add reportMissingProperty property --- .../apex/rule/documentation/ApexDocRule.java | 22 ++++++++++----- .../apex/rule/documentation/xml/ApexDoc.xml | 28 +++++++++++++++++++ 2 files changed, 43 insertions(+), 7 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 13aecd1ff7..5af37e9b76 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 @@ -48,10 +48,15 @@ public class ApexDocRule extends AbstractApexRule { booleanProperty("reportMissingDescription") .desc("Report missing @description").defaultValue(true).build(); + private static final PropertyDescriptor REPORT_MISSING_PROPERTY_DESCRIPTOR = + booleanProperty("reportMissingProperty") + .desc("Report missing properties").defaultValue(true).build(); + public ApexDocRule() { definePropertyDescriptor(REPORT_PRIVATE_DESCRIPTOR); definePropertyDescriptor(REPORT_PROTECTED_DESCRIPTOR); definePropertyDescriptor(REPORT_MISSING_DESCRIPTION_DESCRIPTOR); + definePropertyDescriptor(REPORT_MISSING_PROPERTY_DESCRIPTOR); addRuleChainVisit(ASTUserClass.class); addRuleChainVisit(ASTUserInterface.class); @@ -113,13 +118,16 @@ 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); - } - } else { - if (getProperty(REPORT_MISSING_DESCRIPTION_DESCRIPTOR) && !comment.hasDescription) { - addViolationWithMessage(data, node, MISSING_DESCRIPTION_MESSAGE); + + if (getProperty(REPORT_MISSING_PROPERTY_DESCRIPTOR)) { + if (comment == null) { + if (shouldHaveApexDocs(node)) { + addViolationWithMessage(data, node, MISSING_COMMENT_MESSAGE); + } + } else { + if (getProperty(REPORT_MISSING_DESCRIPTION_DESCRIPTOR) && !comment.hasDescription) { + addViolationWithMessage(data, node, MISSING_DESCRIPTION_MESSAGE); + } } } 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..1b221deccc 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,34 @@ public class Foo { */ public Foo() { } +} + ]]> + + + + property should have comment + true + 1 + + + + + property does not need comment + false + 0 + From ba903437c097c6d5e9344bc19c9b4c87cf652cbe Mon Sep 17 00:00:00 2001 From: Andreas Dangel Date: Tue, 21 Dec 2021 19:04:59 +0100 Subject: [PATCH 2/3] [apex] ApexDoc - handle properties via "reportProperty". --- .../apex/rule/documentation/ApexDocRule.java | 34 +++++++++++-------- .../resources/category/apex/documentation.xml | 4 ++- .../apex/rule/documentation/xml/ApexDoc.xml | 23 +++++++++++-- 3 files changed, 43 insertions(+), 18 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 5af37e9b76..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,25 +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_MISSING_PROPERTY_DESCRIPTOR = - booleanProperty("reportMissingProperty") - .desc("Report missing properties").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_MISSING_PROPERTY_DESCRIPTOR); + definePropertyDescriptor(REPORT_PROPERTY_DESCRIPTOR); addRuleChainVisit(ASTUserClass.class); addRuleChainVisit(ASTUserInterface.class); @@ -119,15 +119,13 @@ public class ApexDocRule extends AbstractApexRule { public Object visit(ASTProperty node, Object data) { ApexDocComment comment = getApexDocComment(node); - if (getProperty(REPORT_MISSING_PROPERTY_DESCRIPTOR)) { - if (comment == null) { - if (shouldHaveApexDocs(node)) { - addViolationWithMessage(data, node, MISSING_COMMENT_MESSAGE); - } - } else { - if (getProperty(REPORT_MISSING_DESCRIPTION_DESCRIPTOR) && !comment.hasDescription) { - addViolationWithMessage(data, node, MISSING_DESCRIPTION_MESSAGE); - } + if (comment == null) { + if (shouldHaveApexDocs(node)) { + addViolationWithMessage(data, node, MISSING_COMMENT_MESSAGE); + } + } else { + if (getProperty(REPORT_MISSING_DESCRIPTION_DESCRIPTOR) && !comment.hasDescription) { + addViolationWithMessage(data, node, MISSING_DESCRIPTION_MESSAGE); } } @@ -159,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 1b221deccc..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 @@ -634,8 +634,9 @@ public class Foo { property should have comment - true + true 1 + 5 + + property with missing description + false + 1 + 8 + + + property does not need comment - false + false 0 Date: Tue, 21 Dec 2021 19:14:24 +0100 Subject: [PATCH 3/3] [doc] Update release notes (#3693) --- docs/pages/release_notes.md | 7 +++++++ 1 file changed, 7 insertions(+) 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 %}