What is the correct way to annotate a return type in an interface?

[PavelTurk]

Please consider two methods in an interface:

@Unmodifiable public List<Foo> getFoos(); 

public @Unmodifiable List<Foo> getFoos(); 

Both variants give an error in Checkstyle: RedundantModifier: Redundant 'public' modifier. As I understand it, these are different: in the first one, the annotation appears to be on the method, and in the second one, on the return type.

If we remove the public modifier:

@Unmodifiable List<Foo> getFoos(); 

then the annotation is interpreted as belonging to the method.

Could someone explain how to properly annotate the return type?

[romani]

Please report question in format of CLI output, as shown at https://github.com/checkstyle/checkstyle/blob/master/.github/ISSUE_TEMPLATE/bug_report.md

It will give us all details we need to help you

[PavelTurk]

@romani You are so cruel :)
https://checkstyle.org/checks/modifier/redundantmodifier.html#RedundantModifier

Test.java:

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import java.util.List;

@Documented
@Retention(RetentionPolicy.CLASS)
@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE_USE})
@interface Unmodifiable { }

class Foo { }

public interface Test {

    @Unmodifiable public List<Foo> getFoos();

    public @Unmodifiable List<Foo> getFoos2();
}

config.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="severity" value="error"/>
    <property name="fileExtensions" value="java"/>

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

command:

/Temp/Test1$ java $RUN_LOCALE -jar checkstyle-13.3.0-all.jar -c config.xml Test.java
Starting audit...
[ERROR] /home/pavel/Temp/Test1/Test.java:17:19: Redundant 'public' modifier. [RedundantModifier]
[ERROR] /home/pavel/Temp/Test1/Test.java:19:5: Redundant 'public' modifier. [RedundantModifier]
Audit done.
Checkstyle ends with 2 errors.

As I understand, if there are annotations before public modifier, then checkstyle shouldn't throw Redundant 'public' modifier error.

[romani]

Thanks a lot !!!
I pretty sure violation is to remove "public" and annotation will be applied to method, due to target of annotation.

Can you just remove public and run again?

May be now we need deeper in meaning of java code, but java should apply annotation in predictable way with or without "public".

[PavelTurk]

This is what ChatGPT says about two methods:

The difference is what the annotation applies to.

@Unmodifiable public List<Foo> getFoos();
The annotation applies to the method itself.

public @Unmodifiable List<Foo> getFoos2();
The annotation applies to the return type (List<Foo>).

So the second form explicitly states that the returned list is unmodifiable, while the first one annotates the method declaration.

So, if you remove public, then you can apply the annotation either to the return type or to the method itself. In other words, you lose half of the capabilities provided by Java. Therefore, it seems that [RedundantModifier] for interfaces is wrong.

[PavelTurk]

I ran several tests with annotations and the public keyword using reflection. However, I was not able to get different results depending on whether public was present or not. As I understand it, the Java compiler determines whether an annotation applies to the method declaration or to the type based on the allowed targets of the annotation (@Target).

However, when annotations are used mainly as hints for developers, the situation is different. A developer usually does not remember the exact @Target of a particular annotation, so the annotation’s position becomes important in order to clearly understand what it applies to. For example https://stackoverflow.com/questions/25958995/where-to-put-nullable-on-methods-with-nullable-return-types