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

[Jonathan Gibbons]

Looks OK to me.

-- Jon


On 11/02/2018 10:02 AM, joe darcy wrote:
> 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){
>