Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MissingJavadocType: Support qualified annotation names #11736

Closed
alexstaeding opened this issue Jun 13, 2022 · 9 comments
Closed

MissingJavadocType: Support qualified annotation names #11736

alexstaeding opened this issue Jun 13, 2022 · 9 comments

Comments

@alexstaeding
Copy link

alexstaeding commented Jun 13, 2022

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.
@checkstyle checkstyle deleted a comment from strkkk Jun 29, 2022
@checkstyle checkstyle deleted a comment from alexstaeding Jun 29, 2022
@checkstyle checkstyle deleted a comment from alexstaeding Jun 29, 2022
@romani
Copy link
Member

romani commented Jun 29, 2022

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

@alexstaeding
Copy link
Author

alexstaeding commented Jun 29, 2022

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
Copy link
Member

romani commented Jun 29, 2022

I think it easy defect in matching logic by name

@romani romani added the easy label Jul 2, 2022
@romani
Copy link
Member

romani commented Jul 2, 2022

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

@stoyanK7
Copy link
Contributor

stoyanK7 commented Jul 3, 2022

@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
Copy link
Member

romani commented Jul 3, 2022

ApiStatus.Internal

To match as is

stoyanK7 added a commit to stoyanK7/checkstyle that referenced this issue Jul 3, 2022
stoyanK7 added a commit to stoyanK7/checkstyle that referenced this issue Jul 3, 2022
stoyanK7 added a commit to stoyanK7/checkstyle that referenced this issue Jul 3, 2022
stoyanK7 added a commit to stoyanK7/checkstyle that referenced this issue Jul 4, 2022
stoyanK7 added a commit to stoyanK7/checkstyle that referenced this issue Jul 4, 2022
stoyanK7 added a commit to stoyanK7/checkstyle that referenced this issue Jul 4, 2022
stoyanK7 added a commit to stoyanK7/checkstyle that referenced this issue Jul 4, 2022
stoyanK7 added a commit to stoyanK7/checkstyle that referenced this issue Jul 5, 2022
stoyanK7 added a commit to stoyanK7/checkstyle that referenced this issue Jul 6, 2022
@strkkk
Copy link
Member

strkkk commented Jul 9, 2022

fix is merged

@strkkk strkkk closed this as completed Jul 9, 2022
@strkkk strkkk added the bug label Jul 9, 2022
@strkkk strkkk added this to the 10.4 milestone Jul 9, 2022
@alexstaeding
Copy link
Author

alexstaeding commented Jul 12, 2022

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

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

@romani
Copy link
Member

romani commented Jul 12, 2022

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

stoyanK7 added a commit to stoyanK7/checkstyle that referenced this issue Jul 13, 2022
stoyanK7 added a commit to stoyanK7/checkstyle that referenced this issue Jul 13, 2022
stoyanK7 added a commit to stoyanK7/checkstyle that referenced this issue Jul 13, 2022
stoyanK7 added a commit to stoyanK7/checkstyle that referenced this issue Jul 14, 2022
@romani romani changed the title Support qualified annotation names MissingJavadocType: Support qualified annotation names Jul 30, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

4 participants