JavadocUtil doesn't recognize Javadocs in certain places

[rnveach]

While looking into #5411 and verifying the statement I made:

We should have a missing for every place a javadoc is valid.

I made a bare bones check to verify we recognize all valid javadoc placements.
InvalidJavadocPositionCheck
https://github.com/rnveach/checkstyle/commits/InvalidJavadocPositionCheck

    public void visitToken(DetailAST ast) {
        final String commentContent = JavadocUtil.getBlockCommentContent(ast);

        if (JavadocUtil.isJavadocComment(commentContent)) {
            if (!JavadocUtil.isCorrectJavadocPosition(ast)) {
                log(ast, "Invalid Javadoc Position");
            }
        }
    }

I expected no violations from this check on Checkstyle's own sources but I get the following:

[ERROR] \src\main\java\com\puppycrawl\tools\checkstyle\api\Configuration.java:32:5: Invalid Javadoc Position [InvalidJavadocPosition]
[ERROR] \src\main\java\com\puppycrawl\tools\checkstyle\api\Configuration.java:46:5: Invalid Javadoc Position [InvalidJavadocPosition]
[ERROR] \src\main\java\com\puppycrawl\tools\checkstyle\api\DetailNode.java:56:5: Invalid Javadoc Position [InvalidJavadocPosition]
[ERROR] \src\main\java\com\puppycrawl\tools\checkstyle\api\TextBlock.java:29:5: Invalid Javadoc Position [InvalidJavadocPosition]

It looks like currently Checkstyle doesn't work with javadocs on methods with no modifiers and returns an array.

You can also see an example with:

$ cat TestClass.java
public class TestClass {
    /** A<p>b */
    void method() {}
    /** A<p>b */
    String[] method2() { return null; }
}

$ cat TestConfig.xml
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
          "-//Puppy Crawl//DTD Check Configuration 1.3//EN"
          "http://www.puppycrawl.com/dtds/configuration_1_3.dtd">

<module name="Checker">
    <property name="charset" value="UTF-8"/>

    <module name="TreeWalker">
<module name="JavadocParagraphCheck" />
    </module>
</module>

$ java -jar checkstyle-8.18-all.jar -c TestConfig.xml TestClass.java
Starting audit...
[ERROR] TestClass.java:2: <p> tag should be preceded with an empty line. [JavadocParagraph]
Audit done.
Checkstyle ends with 1 errors.

There should be 2 violations as both are methods with the same javadoc.

I am going to run regression to see if there are any other cases.

Let me know if we should open another issue to add this check to Checkstyle. It is pretty simple.

[rnveach]

Regression: http://rveach.no-ip.org/checkstyle/regression/reports/231/

These are other false positives that I have seen so far:

http://rveach.no-ip.org/checkstyle/regression/reports/231/lombok-ast/index.html#A3
spotbugs has a few of these too.

http://rveach.no-ip.org/checkstyle/regression/reports/231/elasticsearch/index.html#A12

[romani]

fix is merged.

[rnveach]

As stated in the PR, this wasn't the end to the issue. First regression was clouded with too many results. I wanted to rerun after the first merge to see if there was anymore cases.
I will reopen issue if regression shows more.

[rnveach]

Regression: http://rveach.no-ip.org/checkstyle/regression/reports/236/

I reviewed almost all the violations and I didn't see anymore false positives.