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.