# HG changeset patch
# User darcy
# Date 1541209750 25200
# Node ID 24f37f464da08fd1227faa4f2423500496e5f47c
# Parent  1322829d1501c673fa076bcb8f1ad86ad3cf1563
8213256: Clarify runtime vs compile time annotations for RoundEnvironment.getElementsAnnotatedWith(Class)
Reviewed-by: jjg, jlahoda

diff -r 1322829d1501 -r 24f37f464da0 src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java
--- a/src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java	Fri Nov 02 19:30:31 2018 -0400
+++ b/src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java	Fri Nov 02 18:49:10 2018 -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 javax.lang.model.AnnotatedConstruct#getAnnotation(Class)
+     * @see javax.lang.model.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 javax.lang.model.AnnotatedConstruct#getAnnotation(Class)
+     * @see javax.lang.model.AnnotatedConstruct#getAnnotationsByType(Class)
+     *
      * @since 9
      */
     default Set<? extends Element> getElementsAnnotatedWithAny(Set<Class<? extends Annotation>> annotations){