Summary

Document possible runtime vs compile-time difference in set of annotations present for RoundEnvironment.getElementsAnnotatedWith methods taking a Class object.

Problem

The set of annotation types available at runtime using Class objects may differ from the set of annotation types available at compile time using TypeElement objects. For example, the runtime class path may include type not on the compiler-type paths.

Solution

Note this possibility in the affected methods.

Specification

--- 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 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){