MissingJavadocType: Support qualified annotation names

[alexstaeding]

https://checkstyle.sourceforge.io/config_javadoc.html#MissingJavadocType

I have come across the slight annoyance that I am unable to exclude some annotations from the MissingJavadocType check because they are nested within a class. These are the annotations in question. Currently, the only workaround is to import every nested annotation separately instead of just the enclosing class.

Specifically, I would like to exclude annotations such as @ApiStatus.Internal from MissingJavadocType as follows:

<module name="MissingJavadocType">
    <property name="scope" value="protected"/>
    <property name="tokens"
              value="INTERFACE_DEF, ENUM_DEF, ANNOTATION_DEF"/>
    <property name="excludeScope" value="nothing"/>
    <property name="skipAnnotations" value="ApiStatus.Internal"/> <!-- this does not work -->
</module>

From the docs:

Only short names are allowed, e.g. Generated.

Example affected file(s)

Checkstyle config here, relevant part here

Example error:

> Task :jagr-grader-api:checkstyleMain FAILED
[ant:checkstyle] [WARN] /home/alex/IdeaProjects/Jagr/grader-api/src/main/java/org/sourcegrade/jagr/api/rubric/Criterion.java:239:5: Missing a Javadoc comment. [MissingJavadocType]

...

Execution failed for task ':jagr-grader-api:checkstyleMain'.

Minimal example

https://github.com/alexstaeding/CheckStyle-Issue11736

/**
 * Ignore.
 */
public interface Foo {

    @ApiStatus.Internal
    interface A {
    }

    @Internal
    interface B {
    }
}

It is currently not possible to provide a value for skipAnnotations so that this Foo.A interface does not require javadoc. This is specifically mentioned in the docs.

<property name="skipAnnotations" value="ApiStatus.Internal"/> <!-- this does not work -->

CLI (executed in this repository):

$ cat config/checkstyle/checkstyle.xml 
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
        "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
        "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
    <property name="charset" value="UTF-8"/>
    <property name="fileExtensions" value="java, properties, xml"/>
    <module name="TreeWalker">
        <module name="MissingJavadocType">
            <property name="scope" value="protected"/>
            <property name="tokens"
                      value="INTERFACE_DEF, ENUM_DEF, ANNOTATION_DEF"/>
            <property name="excludeScope" value="nothing"/>
            <property name="skipAnnotations" value="Internal"/> <!-- this does not work -->
        </module>
    </module>
</module>

$ cat src/main/java/Foo.java 
import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.ApiStatus.Internal;

/**
 * Ignore.
 */
public interface Foo {

    @ApiStatus.Internal
    interface A {

    }

    @Internal
    interface B {

    }
}

java -jar checkstyle-10.3.1-all.jar -c config/checkstyle/checkstyle.xml src/main/java/Foo.java
Starting audit...
[ERROR] ***/IdeaProjects/CheckStyle-Issue11736/src/main/java/Foo.java:9:5: Missing a Javadoc comment. [MissingJavadocType]
Audit done.
Checkstyle ends with 1 errors.

[romani]

Can you update your CLI example config like:
<property name="skipAnnotations" value="Internal, ApiStatus.Internal"/>

[alexstaeding]

Can you update your CLI example config like: <property name="skipAnnotations" value="Internal, ApiStatus.Internal"/>

$ cat config/checkstyle/checkstyle.xml 
<?xml version="1.0"?>
<!DOCTYPE module PUBLIC
        "-//Checkstyle//DTD Checkstyle Configuration 1.3//EN"
        "https://checkstyle.org/dtds/configuration_1_3.dtd">
<module name="Checker">
    <property name="charset" value="UTF-8"/>
    <property name="fileExtensions" value="java, properties, xml"/>
    <module name="TreeWalker">
        <module name="MissingJavadocType">
            <property name="scope" value="protected"/>
            <property name="tokens"
                      value="INTERFACE_DEF, ENUM_DEF, ANNOTATION_DEF"/>
            <property name="excludeScope" value="nothing"/>
            <property name="skipAnnotations" value="Internal, ApiStatus.Internal"/>
        </module>
    </module>
</module>

$ cat src/main/java/Foo.java 
import org.jetbrains.annotations.ApiStatus;
import org.jetbrains.annotations.ApiStatus.Internal;

/**
 * Ignore.
 */
public interface Foo {

    @ApiStatus.Internal
    interface A {

    }

    @Internal
    interface B {

    }
}

java -jar checkstyle-10.3.1-all.jar -c config/checkstyle/checkstyle.xml src/main/java/Foo.java
Starting audit...
[ERROR] ***/IdeaProjects/CheckStyle-Issue11736/src/main/java/Foo.java:9:5: Missing a Javadoc comment. [MissingJavadocType]
Audit done.
Checkstyle ends with 1 errors.

[romani]

I think it easy defect in matching logic by name

[romani]

@stoyanK7 , can you help us to fix this issue ?
I think it is good issue to start.

[stoyanK7]

@romani On it! I found the cause. My question is:
Should

<property name="skipAnnotations" value="Internal"/>

skip both @Internal and @ApiStatus.Internal or just @Internal?

[romani]

ApiStatus.Internal

To match as is

[strkkk]

fix is merged

[alexstaeding]

Thanks, may I suggest also updating the docs as this is no longer accurate:

Only short names are allowed, e.g. Generated.

[romani]

@stoyanK7, please send one more PR that reference the same issue.