--- old/src/share/classes/java/lang/reflect/AnnotatedElement.java 2013-12-04 17:55:00.000000000 -0800
+++ new/src/share/classes/java/lang/reflect/AnnotatedElement.java 2013-12-04 17:55:00.000000000 -0800
@@ -135,7 +135,78 @@
* annotations on E are directly present on E in place
* of their container annotation, in the order in which they appear in
* the value element of the container annotation.
-
+ *
+ *
There are several compatibility concerns to keep in mind if an
+ * annotation type T is originally not repeatable and
+ * later modified to be repeatable.
+ *
+ * The containing annotation type for T is TC.
+ *
+ *
+ *
+ * - Modifying T to be repeatable is source and binary
+ * compatible with existing uses of T and with existing uses
+ * of TC.
+ *
+ * That is, for source compatibility, source code with annotations of
+ * type T or of type TC will still compile. For binary
+ * compatibility, class files with annotations of type T or of
+ * type TC (or with other kinds of uses of type T or of
+ * type TC) will link against the modified version of T
+ * if they linked against the earlier version.
+ *
+ * (An annotation type TC may informally serve as an acting
+ * containing annotation type before T is modified to be
+ * formally repeatable. Alternatively, when T is made
+ * repeatable, TC can be introduced as a new type.)
+ *
+ *
- If an annotation type TC is present on an element, and
+ * T is modified to be repeatable with TC as its
+ * containing annotation type then:
+ *
+ *
+ *
+ * - The change to T is behaviorally compatible with respect
+ * to the {@code get[Declared]Annotation(Class)} (called with an
+ * argument of T or TC) and {@code
+ * get[Declared]Annotations()} methods because the results of the
+ * methods will not change due to TC becoming the containing
+ * annotation type for T.
+ *
+ *
- The change to T is not behaviorally compatible
+ * with respect to the {@code
+ * get[Declared]AnnotationsByType(Class)} methods, because those
+ * methods will now recognize an annotation of type TC as a
+ * container annotation and will "look through" it to expose
+ * annotations of type T.
+ *
+ *
+ *
+ * - If an annotation of type T is present on an
+ * element and T is made repeatable and more annotations of
+ * type T are added to the element:
+ *
+ *
+ *
+ * - The addition of the additional annotations is both source
+ * compatible and binary compatible.
+ *
+ *
- The addition of the additional annotations changes the results
+ * of the {@code get[Declared]Annotation(Class)} methods and {@code
+ * get[Declared]Annotations()} methods, because those methods will now
+ * only see a container annotation on the element and not see an
+ * annotation of type T.
+ *
+ *
- The addition of the additional annotations changes the results
+ * of the {@code get[Declared]AnnotationsByType(Class)} methods,
+ * because their results will expose the additional annotations of
+ * type T whereas previously they exposed only a single
+ * annotation of type T.
+ *
+ *
+ *
+ *
+ *
* If an annotation returned by a method in this interface contains
* (directly or indirectly) a {@link Class}-valued member referring to
* a class that is not accessible in this VM, attempting to read the class