Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-8157424

Javadoc of java.lang.annotation.Repeatable is lacking; and documentation on the Oracle site is wrong

    XMLWordPrintable

    Details

    • Subcomponent:
    • CPU:
      generic
    • OS:
      generic

      Description

      A DESCRIPTION OF THE REQUEST :
      The javadoc of Repeatable only says this:

      ----
      The annotation type java.lang.annotation.Repeatable is used to indicate that the annotation type whose declaration it (meta-)annotates is repeatable. The value of @Repeatable indicates the containing annotation type for the repeatable annotation type.
      ----

      The references are to chapters of the JLS (with no clickable links; that hurts in 2016).

      After a quick search, I stumbled upon this link:

      http://docs.oracle.com/javase/tutorial/java/annotations/repeating.html

      But the documentation itself is wrong; it says that (emphasis mine):

      ----
      [...] For compatibility reasons, repeating annotations are stored in a container annotation that is **automatically generated by the Java compiler**.
      ----

      But what follows contradicts the "automatically generated" part, since it is required that the developer declare the two annotations (the repeated annotation and the container annotation).

      Suggestion:

      * give an example in the Repeatable javadoc;
      * fix the documentation on the site: the container annotation _is not_ automatically generated.

      JUSTIFICATION :
      Repeatable annotations is quite a nice feature; but the lack of a practical head start in the javadoc is disturbing.

      While a determined developer can work out the details using his/her search skills and existing Java language skills, not every developer is that much determined/fluent.

      The proposed enhancements are simple enough that they can be implemented easily, and will help developers a great deal into making actual use of this feature.


        Attachments

          Activity

            People

            Assignee:
            darcy Joe Darcy
            Reporter:
            webbuggrp Webbug Group
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Dates

              Created:
              Updated:
              Resolved: