[apex] Add validation of ApexDoc comments #1314

jeffhube · 2018-08-21T16:55:54Z

Please, prefix the PR title with the language it applies to within brackets, such as [java] or [apex]. If not specific to a language, you can use [core]

Before submitting a PR, please check that:

The PR is submitted against master. The PMD team will merge back to support branches as needed.
./mvnw test passes.
./mvnw pmd:check passes.
./mvnw checkstyle:check passes. Check this for more info

PR Description:

This rule validates that:

ApexDoc comments are present for classes, methods, and properties that are public or global, excluding overrides and test classes (as well as the contents of test classes).
ApexDoc comments should contain @description.
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.

Since comments are not present in the AST, this rule expects the ApexDoc comment to be the first non-whitespace token that starts above the line containing either the first annotation if present, otherwise the class/method/property name (since that is considered to be the start of the class/method/property node). This does require the source code in string form, which I am capturing in ApexRootNode, and also tokenizing in the rule using ApexLexer. Suggestions of better ways to handle this are welcome.

Finds ApexDoc Comment:

/**
 * @description Foo
 */
public class Foo { }

/**
 * @description Foo
 */
@Deprecated
public class Foo { }

/**
 * @description Foo
 */

public class Foo { }

Does not find ApexDoc comment:

/**
 * @description Foo
 */
// foo
public class Foo { }

/** @description Foo */ public class Foo { }

/**
 * @description Foo
 */
public class
Foo { }

jeffhube · 2018-08-21T17:01:15Z

pmd-apex/src/main/resources/category/apex/documentation.xml

@@ -8,4 +8,23 @@
    <description>
 Rules that are related to code documentation.
    </description>
+
+    <rule name="ApexDoc"
+          since="9.9.9"


Which version?

At the time, the next release would be 6.7.0

jeffhube · 2018-08-21T17:04:58Z

pmd-apex/src/main/resources/rulesets/apex/ruleset.xml

+      <properties>
+         <!-- relevant for Code Climate output only -->
+         <property name="cc_categories" value="Style" />
+         <property name="cc_remediation_points_multiplier" value="50" />


What should the multiplier be?

See here for explanation of remediation points: https://github.com/codeclimate/spec/blob/master/SPEC.md#remediation-points

In the implementation of our CodeClimateRenderer, we use the baseline of 50_000 (which is the estimated required time for a trivial fix) and multiply it with the property defined here: https://github.com/pmd/pmd/blob/master/pmd-core/src/main/java/net/sourceforge/pmd/renderers/CodeClimateRenderer.java#L124-L132

I see, that we use multipliers between 1 and 250. Fixing missing documentation can be time consuming and we provide here a rough guess across all types of missing doc (class documentation might take more effort than a property documentation).

IMHO, 50 sounds like a reasonable value to me.

pmd-test · 2018-08-21T17:10:31Z

	1 Message
📖	No java rules are changed!

Generated by 🚫 Danger

jsotuyod · 2018-08-23T06:12:42Z

@jeffhube thanks for the contribution. This is a very interesting approach to rebuilding comment info from source, I didn't realize we had that handleSourceCode override...

The approach however seems not very extensible (having the rule parse everything and find comments), so we should probably analyze these very interesting ideas you bring and see if we can work out a more extensible approach. Let us ponder a few days on this and come back to you with our thoughts.

jsotuyod · 2018-08-27T16:46:33Z

I've been thinking about this, and I believe we should move the parsing to ApexTreeBuilder, and have the doc (comment starting with /**) be an actual AST tree (ASTFormalComment for consistency with Java). Other comments can be dropped for the time being (but this would be groundwork for implementing #1087).

Doing so would require:

Have the lexer initialized in the ApexTreeBuilder constructor
Have the ASTFormalComment node extend AbstractNode and implement Node. Notice we can't extend AbstractApexNode nor implement ApexNode as there is no underlying node from Jorje. This would probably need a new abstract class above AbstractApexNode to implement all Node methods without repetition between ASTFormalComment and AbstractApexNode.
Have ApexTreeBuilder.build check if a node has a ASTFormalComment on top, and have it added to the tree structure.

Once that's done, the rule could be updated to simply visiting the nodes that require doc, and transversing the tree to look for those nodes without parsing.

jeffhube · 2018-08-28T22:14:21Z

Here is where I am at so far:

Added a class between AbstractApexNode<T> and AbstractNode named AbstractApexNodeBase (naming?)
Moved methods that aren't dependent on an underlying node from Jorje from AbstractApexNode<T> to AbstractApexNodeBase
Created ASTFormalComment which extends AbstractApexNodeBase
Added visit() for ASTFormalComment and AbstractApexNodeBase to ApexParserVisitor, ApexParserVisitorAdapter, and AbstractApexRule
ApexTreeBuilder tokenizes the source code in its constructor
ApexTreeBuilder constructs ASTFormalComment nodes in visitEnd() for UserClass / UserInterface / Method / Property, see more notes below.
Added test cases for interfaces and for methods and properties preceded by annotations
~~TODO: ASTFormalComment does not have its location set~~
~~TODO: ASTFormalComment should probably be the first child, currently it is the last~~

Construction of `ASTFormalComment` nodes

Currently the ASTFormalComment is built in visitEnd() because I need to look for an ASTAnnotation, and if I find one, adjust the location of where I look for a comment. The ASTAnnotation has been built and visited by the time visitEnd() is called for classes etc, so I can find it easily. Another approach would be to call traverse() on the Jorje node and find the Jorje annotation node before the ASTAnnotation is built.

And the reason for this mess is the incorrect positioning on ASTUserClass, ASTMethod, ASTModifierNode, etc. In the following code snippet, both ASTUserClass and its child ASTModifierNode start at the first character of the class name, Foo, after the class token and any modifiers. The ASTAnnotation, which is also a child of ASTUserClass , starts before it on the @ as you would expect. So that is why building the ASTFormalComment is currently handled in the relevant visit() methods and not in build() as you mentioned above.

@Deprecated
public class Foo { }

jsotuyod · 2018-08-29T01:35:26Z

@jeffhube I'm impressed by your progress so far! Thanks for being so awesome.

TODO: ASTFormalComment should probably be the first child, currently it is the last

yes! definitely! We want the tree to mirror the code as much as possible!

One more thing I've just noticed, you seem to assume any previous formal comment belongs to a given class / method / property / etc. So in an example such as:

/**
 * Some comment
 */
public with sharing class Simple {
    public String someParam { get; set; }

    public void getInit() {
        someParam = "test"; 
    }
}

All 3, the class, the property AND the method will have an ASTFormalComment attached, with the "some comment" content.

jeffhube · 2018-08-29T17:50:23Z

Thanks, @jsotuyod !

I've fixed the outstanding items I mentioned above. The ASTFormalComment is now the first child and has positioning info.

I've not been able to reproduce the issue you mentioned. Looking at that code snippet in the designer, I only see a single comment node, parented to the class. That case should also be covered by unit tests like this one:

    <test-code>
        <description>public method should have comment</description>
        <expected-problems>1</expected-problems>
        <code><![CDATA[
/**
 * @description Foo
 */
public class Foo {
    public void bar() { }
}
        ]]></code>
    </test-code>

adangel

Amazing!
I've just a few minor things, but we can fix them upon merge.
This looks ready, WDYT @jsotuyod ?

adangel · 2018-09-11T12:33:12Z

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

+        return null;
+    }
+
+    private class ApexDocComment {


This should be a private static class

adangel · 2018-09-11T12:34:00Z

pmd-apex/src/main/resources/category/apex/documentation.xml

@@ -8,4 +8,23 @@
    <description>
 Rules that are related to code documentation.
    </description>
+
+    <rule name="ApexDoc"
+          since="6.7.0"


This is by now 6.8.0 😄

adangel · 2018-09-11T12:43:34Z

pmd-apex/src/main/resources/rulesets/apex/ruleset.xml

+      <properties>
+         <!-- relevant for Code Climate output only -->
+         <property name="cc_categories" value="Style" />
+         <property name="cc_remediation_points_multiplier" value="50" />


See here for explanation of remediation points: https://github.com/codeclimate/spec/blob/master/SPEC.md#remediation-points

In the implementation of our CodeClimateRenderer, we use the baseline of 50_000 (which is the estimated required time for a trivial fix) and multiply it with the property defined here: https://github.com/pmd/pmd/blob/master/pmd-core/src/main/java/net/sourceforge/pmd/renderers/CodeClimateRenderer.java#L124-L132

I see, that we use multipliers between 1 and 250. Fixing missing documentation can be time consuming and we provide here a rough guess across all types of missing doc (class documentation might take more effort than a property documentation).

IMHO, 50 sounds like a reasonable value to me.

adangel · 2018-09-11T12:47:18Z

pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/ast/AbstractApexNodeBase.java

+        super(klass.hashCode());
+    }
+
+    public void calculateLineNumbers(SourceCodePositioner positioner, int startOffset, int endOffset) {


This method should not be public - it's enough, if it can be called from classes within the same package (net.sourceforge.pmd.lang.apex.ast).

adangel · 2018-09-11T12:51:31Z

pmd-apex/src/main/resources/category/apex/documentation.xml

+          class="net.sourceforge.pmd.lang.apex.rule.documentation.ApexDocRule"
+          externalInfoUrl="${pmd.website.baseurl}/pmd_rules_apex_documentation.html#apexdoc">
+        <description>
+Identifies missing or incorrect ApexDoc comments.


We should enhance the description from your PR description:

This rule validates that:

ApexDoc comments are present for classes, methods, and properties that are public or global, excluding
overrides and test classes (as well as the contents of test classes).

ApexDoc comments should contain @description.

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.

jsotuyod · 2018-09-12T03:55:26Z

@jeffhube well done!

@adangel I'm having a hell of a week, but I'll review during the weekend at the very latest.

jsotuyod

I'll edit when I merge.

jsotuyod · 2018-09-22T08:29:33Z

pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/ast/AbstractApexNodeBase.java

+    }
+
+    public AbstractApexNodeBase(Class<?> klass) {
+        super(klass.hashCode());


all instances of a node type using this constructor would have the same id.. I'm not sure it would affect our current use, but maybe we should avoid this?

nevermind, we already did it this way.. to be revised in a different PR

jsotuyod · 2018-09-22T08:32:09Z

pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/ast/ApexTreeBuilder.java

+    private TokenLocation getApexDocTokenLocation(int index) {
+        TokenLocation last = null;
+        for (TokenLocation location : tokenLocations) {
+            if (location.index >= index) {


the tokenLocations list is sorted, we can probably be smarter about this search

jsotuyod · 2018-09-22T08:34:57Z

pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/ast/ApexTreeBuilder.java

+        ApexLexer lexer = new ApexLexer(stream);
+
+        ArrayList<TokenLocation> tokenLocations = new ArrayList<>();
+        Integer startIndex = 0;


this should be a primitive

jsotuyod · 2018-09-22T08:35:01Z

pmd-apex/src/main/java/net/sourceforge/pmd/lang/apex/ast/ApexTreeBuilder.java

+        ArrayList<TokenLocation> tokenLocations = new ArrayList<>();
+        Integer startIndex = 0;
+        Token token = lexer.nextToken();
+        Integer endIndex = lexer.getCharIndex();


this should be a primitive

jsotuyod · 2018-09-22T22:58:12Z

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

+    @Override
+    public Object visit(ASTAnnotation node, Object data) {
+        if (node.getImage().equals("IsTest")) {
+            inTestClass = true;


also, this variable is never being reset

jsotuyod · 2018-09-23T05:32:42Z

Merged! Thanks @jeffhube for the amazing job!

I fixed all comments and reworked the parsing a little...

I do not take all token locations, only comments
I create formal comments at visit start rather than visitEnd, which allows me to create them in order…
… which allowed me to drop the searching and simply keep an iterator on the TokenLocations and consume them in order

This will be part of PMD 6.8.0. The groundwork for #1087 is now in place, I left a TODO there.

Thanks again for the contribution!

Add ApexDocRule

d500e7b

jeffhube commented Aug 21, 2018

View reviewed changes

Update rule since version

cba80b2

jeffhube added 2 commits August 27, 2018 15:58

Remove autogenerated doc changes

a17f38a

Merge branch 'master' into apexdoc

42ab055

jsotuyod added the is:WIP For PRs that are not fully ready, or issues that are actively being tackled label Aug 28, 2018

Add ASTFormalComment

df7cc1c

jeffhube added 2 commits August 29, 2018 12:26

Add ASTFormalComment as first child, calculate position

e86166e

Revert changes to ApexRootNode

86dc44d

adangel reviewed Sep 11, 2018

View reviewed changes

adangel removed the is:WIP For PRs that are not fully ready, or issues that are actively being tackled label Sep 11, 2018

adangel added this to the 6.8.0 milestone Sep 11, 2018

jsotuyod reviewed Sep 22, 2018

View reviewed changes

jsotuyod merged commit 86dc44d into pmd:master Sep 23, 2018

jsotuyod added a commit that referenced this pull request Sep 23, 2018

Update changelog, refs #1314

d5d0837

This was referenced Sep 23, 2018

[apex] Support suppression via //NOPMD #1087

Closed

[apex] Apex equivalent for Java's CommentRequiredRule #1136

Closed

rsoesemann mentioned this pull request Oct 17, 2018

[apex] ClassCastException caused by Javadoc #1396

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[apex] Add validation of ApexDoc comments #1314

[apex] Add validation of ApexDoc comments #1314

jeffhube commented Aug 21, 2018 •

edited

Loading

jeffhube Aug 21, 2018

jsotuyod Aug 21, 2018

jeffhube Aug 21, 2018

adangel Sep 11, 2018

pmd-test commented Aug 21, 2018

jsotuyod commented Aug 23, 2018

jsotuyod commented Aug 27, 2018 •

edited

Loading

jeffhube commented Aug 28, 2018 •

edited

Loading

jsotuyod commented Aug 29, 2018

jeffhube commented Aug 29, 2018

adangel left a comment

adangel Sep 11, 2018

adangel Sep 11, 2018

adangel Sep 11, 2018

adangel Sep 11, 2018

adangel Sep 11, 2018

jsotuyod commented Sep 12, 2018

jsotuyod left a comment

jsotuyod Sep 22, 2018

jsotuyod Sep 22, 2018

jsotuyod Sep 22, 2018

jsotuyod Sep 22, 2018

jsotuyod Sep 22, 2018

jsotuyod Sep 22, 2018

jsotuyod commented Sep 23, 2018

[apex] Add validation of ApexDoc comments #1314

[apex] Add validation of ApexDoc comments #1314

Conversation

jeffhube commented Aug 21, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pmd-test commented Aug 21, 2018

jsotuyod commented Aug 23, 2018

jsotuyod commented Aug 27, 2018 • edited Loading

jeffhube commented Aug 28, 2018 • edited Loading

Construction of ASTFormalComment nodes

jsotuyod commented Aug 29, 2018

jeffhube commented Aug 29, 2018

adangel left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jsotuyod commented Sep 12, 2018

jsotuyod left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jsotuyod commented Sep 23, 2018

jeffhube commented Aug 21, 2018 •

edited

Loading

jsotuyod commented Aug 27, 2018 •

edited

Loading

jeffhube commented Aug 28, 2018 •

edited

Loading

Construction of `ASTFormalComment` nodes