JDK 12 RFR of JDK-8213256: Clarify runtime vs ,compile time annotations for ,RoundEnvironment.getElementsAnnotatedWith(Class)

[joe darcy]

Hello,

As a follow-up to recent discussions, please review the proposed changes 
and CSR for

     JDK-8213256: Clarify runtime vs ,compile time annotations for 
,RoundEnvironment.getElementsAnnotatedWith(Class)
     CSR:  https://bugs.openjdk.java.net/browse/JDK-8213310
     webrev: http://cr.openjdk.java.net/~darcy/8213256.0/

Patch below.

Thanks,

-Joe

--- 
old/src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java 
2018-11-02 09:55:44.074001000 -0700
+++ 
new/src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java 
2018-11-02 09:55:43.902001000 -0700
@@ -143,11 +143,26 @@
       * simply because a {@code module-info} file for that module was
       * created.
       *
+     * <p> Note: An implementation of this method typically performs
+     * an internal conversion from the runtime reflective
+     * representation of an annotation type as a {@code Class} object
+     * to a different representation used for annotation
+     * processing. The set of annotation types present in the runtime
+     * context may differ from the set of annotation types present in
+     * the context of annotation processing in a particular
+     * environmental configuration. If an runtime annotation type is
+     * not present in the annotation processing context, the situation
+     * is not treated as an error and no elements are found for that
+     * annotation type.
+     *
       * @param a  annotation type being requested
       * @return the elements annotated with the given annotation type,
       * or an empty set if there are none
       * @throws IllegalArgumentException if the argument does not
       * represent an annotation type
+     *
+     * @see AnnotatedConstruct.getAnnotation(Class)
+     * @see AnnotatedConstruct.getAnnotationsByType(Class)
       */
      Set<? extends Element> getElementsAnnotatedWith(Class<? extends 
Annotation> a);

@@ -155,6 +170,18 @@
       * Returns the elements annotated with one or more of the given
       * annotation types.
       *
+     * <p> Note: An implementation of this method typically performs
+     * an internal conversion from the runtime reflective
+     * representation of an annotation type as a {@code Class} object
+     * to a different representation used for annotation
+     * processing. The set of annotation types present in the runtime
+     * context may differ from the set of annotation types present in
+     * the context of annotation processing in a particular
+     * environmental configuration. If an runtime annotation type is
+     * not present in the annotation processing context, the situation
+     * is not treated as an error and no elements are found for that
+     * annotation type.
+     *
       * @apiNote This method may be useful when processing repeating
       * annotations by looking for an annotation type and its
       * containing annotation type at the same time.
@@ -172,6 +199,10 @@
       * @throws IllegalArgumentException if the any elements of the
       * argument set do not represent an annotation type
       * @jls 9.6.3 Repeatable Annotation Types
+     *
+     * @see AnnotatedConstruct.getAnnotation(Class)
+     * @see AnnotatedConstruct.getAnnotationsByType(Class)
+     *
       * @since 9
       */
      default Set<? extends Element> 
getElementsAnnotatedWithAny(Set<Class<? extends Annotation>> annotations){