hiifong/pmd
1
0
Fork 0
forked from phoedos/pmd
Code Pull Requests Activity

[apex] ApexDoc - handle properties via "reportProperty".

Browse Source
This commit is contained in:
Andreas Dangel 2021-12-21 19:04:59 +01:00
parent abfdb572d3
commit ba903437c0
No known key found for this signature in database
GPG Key ID: 93450DF2DF9A3FA3
3 changed files with 43 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/rule/documentation/ApexDocRule.java
View File

@ -38,25 +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_MISSING_PROPERTY_DESCRIPTOR =
booleanProperty("reportMissingProperty")
.desc("Report missing properties").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_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;
}

4
pmd-apex/src/main/resources/category/apex/documentation.xml
View File

@ -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>

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

@ -634,8 +634,9 @@ public class Foo {
<test-code>
<description>property should have comment</description>
<rule-property name="reportMissingProperty">true</rule-property>
<rule-property name="reportProperty">true</rule-property>
<expected-problems>1</expected-problems>
<expected-linenumbers>5</expected-linenumbers>
<code><![CDATA[
/**
* @description Foo
@ -646,9 +647,27 @@ public class Foo {
]]></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="reportMissingProperty">false</rule-property>
<rule-property name="reportProperty">false</rule-property>
<expected-problems>0</expected-problems>
<code><![CDATA[
/**