JDK-8175533 : Documented annotations show up twice in Javadoc for fields and parameters
  • Type: Bug
  • Component: tools
  • Sub-Component: javac
  • Affected Version: 8,9
  • Priority: P3
  • Status: Open
  • Resolution: Unresolved
  • OS: generic
  • CPU: generic
  • Submitted: 2017-02-22
  • Updated: 2023-09-03
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
tbdUnresolved
Related Reports
Relates :  
Relates :  
Description
FULL PRODUCT VERSION :
java version "1.8.0_121"
Java(TM) SE Runtime Environment (build 1.8.0_121-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.121-b13, mixed mode)

ADDITIONAL OS VERSION INFORMATION :
OS X 10.10.5

A DESCRIPTION OF THE PROBLEM :
Annotations meta-annotated with @Documented show up twice in the JavaDoc when given on a public field or method parameter.

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
mkdir -p src/main/java/com/example

cat > src/main/java/com/example/MyAnno.java <<EOL
package com.example;

import static java.lang.annotation.ElementType.*;
import static java.lang.annotation.RetentionPolicy.RUNTIME;

import java.lang.annotation.*;

@Documented
@Target({ TYPE, METHOD, FIELD, CONSTRUCTOR, PARAMETER, TYPE_USE })
@Retention(RUNTIME)
public @interface MyAnno {
}
EOL

cat > src/main/java/com/example/MyAnnoUser.java <<EOL
package com.example;

import java.util.List;

public class MyAnnoUser {

    @MyAnno public String foo;
    public void doFoo(@MyAnno String foo) {}
}
EOL

javadoc -sourcepath src/main/java -d target/javadoc $(find src/main/java -name "*.java")

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
In the field/method details section of MyAnnoUser, the MyAnno annotation should be shown once for each usage:

public @MyAnno java.lang.String foo

public void doFoo(@MyAnno java.lang.String foo)
ACTUAL -
The MyAnno annotation is show twice for each usage:

@MyAnno
public @MyAnno java.lang.String foo

public void doFoo(@MyAnno
                  @MyAnno java.lang.String foo)

REPRODUCIBILITY :
This bug can be reproduced always.

---------- BEGIN SOURCE ----------
See above (steps to reproduce)
---------- END SOURCE ----------


Comments
Hi, I think this issue comes down to the fact that the annotation applies to TYPE_USE (type context) as well as PARAMETER, FIELD, etc. (declaration context). According to the JLS ยง 9.7.4, the annotation applies to both the type context and the declaration context in such situations. > If the annotation's interface is applicable in the declaration context corresponding to the declaration and in type contexts, then the annotation is deemed to apply to both the declaration and the type which is closest to the annotation. This is also obversable via reflections, the annotation is part of both AnnotatedElement and AnnotatedType. So I'm not sure if this is actually a javac issue, as it only does what it needs to do (from my understanding). However, I think the annotations should be deduplicated *somewhere* from a usability perspective.
03-09-2023

Curious, there does not appear to be anything in 8 b75 to directly cause this change: https://bugs.openjdk.java.net/issues/?jql=project%20%3D%20jdk%20and%20Subcomponent%3D%22javadoc%28tool%29%22%20and%20fixVersion%3D8%20and%20%22Resolved%20In%20Build%22%3Db75 I see doclint stuff, but nothing that would/should impact the output. It's doubly curious that it shows up in 8 and 9 -- i.e. both old and new standard doclet. Looking at the changes for javac in 8b75, https://bugs.openjdk.java.net/issues/?jql=project%20%3D%20jdk%20and%20Subcomponent%3D%22javac%22%20and%20fixVersion%3D8%20and%20%22Resolved%20In%20Build%22%3Db75 This one stands out: https://bugs.openjdk.java.net/browse/JDK-8006775 i.e. JSR 308, the Type Annotations work. That strongly suggests this is a javac issue, and that the duplicate annotations are being "produced" by javac. Reassigning to javac team.
25-02-2017

This regression is introduced in 8 ea b75 8 ea b74 - Pass 8 ea b75 - Fail
23-02-2017

This is an issue reproducible both in 8u121 and 9 ea b157 == public void doFoo(@MyAnno @MyAnno java.lang.String foo) == This is an regression works fine in 7u and fails in 8 and 9 builds 7u45 - Pass 8uxx - Fail 9 eab157 - Fail
23-02-2017