JDK-8278592 : Documented annotations with target TYPE_USE and PARAMETER are duplicated
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 8-pool,11,16,17,18
  • Priority: P4
  • Status: Open
  • Resolution: Unresolved
  • OS: generic
  • CPU: generic
  • Submitted: 2021-12-07
  • Updated: 2022-03-14
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
ADDITIONAL SYSTEM INFORMATION :
OS: Windows 10 20H2 (build 19042.1348)

Java runtime:
openjdk version "18-beta" 2022-03-22
OpenJDK Runtime Environment Temurin-18+26-202112030041 (build 18-beta+26-202112030041)
OpenJDK 64-Bit Server VM Temurin-18+26-202112030041 (build 18-beta+26-202112030041, mixed mode, sharing)

A DESCRIPTION OF THE PROBLEM :
Documented annotations that combine target TYPE_USE and other valid targets such as PARAMETER, are duplicated in the class data, and so on documentation too

The duplication also happens if any other target type which is valid to the context is present, this causes annotations such as JetBrains's @NotNull and @Nullable to be duplicated in the class data, as well as on the javadocs, on return types or on parameters for example

The bug is reproducible on :
JDK 8u265
JDK 11.0.6+10
JDK 16.0.2+7
JDK 18-EA+26

Related issues:
https://bugs.openjdk.java.net/browse/JDK-8175533

Seems to be related:
https://bugs.openjdk.java.net/browse/JDK-8006775

Other issues caused by the bug:
https://github.com/JetBrains/java-annotations/issues/37 : "I.e. overlapping scopes lead to tools such as Javadoc recognizing both targets as matched thus leading to issues such as duplication of the annotation in documentation"

REGRESSION : Last worked in version 8

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
1. Make any class with an annotated element that is allowed by two targets (TYPE_USE and PARAMETER here)

API.java:

@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.PARAMETER, ElementType.TYPE_USE})
@interface TypeUseAnnot {}

public class API {
	public static void doSomething(@TypeUseAnnot Object obj) { }
}


Generating the docs:
javadoc -d docs API.java

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
The @TypeUseAnnot annotation should only appear once in the class data and also in the method detail section javadoc
ACTUAL -
The @TypeUseAnnot annotation is duplicated on the "obj" parameter

---------- BEGIN SOURCE ----------
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.PARAMETER, ElementType.TYPE_USE})
@interface TypeUseAnnot {}

public class API {
	public static void doSomething(@TypeUseAnnot Object obj) { }
}
---------- END SOURCE ----------

FREQUENCY : always



Comments
In the class file, the behavior looks reasonable, since the annotation is listed just once in each of two different groups/kinds of annotations. The javadoc behavior looks less defensible; when copied into the source, the result shows a compilation error (not a valid repeatable annotation)
14-03-2022

The issue is reproducible. Use javadoc -d o API.java to reproduce the issue with the attached reproducer. In method details sectoin @TypeUseAnnot is used twice in the parameter list of the method doSomething
13-12-2021