phoedos/pmd
1
1
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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.

Browse Source
This commit is contained in:
Scott Wells 2021-10-20 11:42:52 -05:00
parent adaf031311
commit efbe149f21
3 changed files with 66 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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);
}
}

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

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

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

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