Review request for present, directly present, etc. in core reflection javadoc

[Alex Buckley]

Hi Joe,

Thanks for applying these spec changes to the API. I note the 
refactoring in get[Declared]AnnotationByType so that the order of 
directly + indirectly present annotations is specified earlier.

One omission: getDeclaredAnnotationsByType still says it returns 
directly present annotations, when it should say directly _or 
indirectly_ present annotations. After all, that method is different 
than getDeclaredAnnotations precisely because of look-through. Please 
see item 2 in the bug.

Alex

On 7/9/2013 2:41 PM, Joe Darcy wrote:
> Hello,
>
> Please review the patch below which incorporates the "present",
> "directly present", "associated", etc. terminology into the
> AnnotatedElement interface in core reflection. This is wholly analogous
> to the previous work of using that terminology in the AnnotatedConstruct
> interface in javax.lang.model.model.
>
> Full webrev viewable at:
>
>      http://cr.openjdk.java.net/~darcy/8010679.0/
>
> Thanks,
>
> -Joe
>
> diff -r 83c2976ef8ee
> src/share/classes/java/lang/reflect/AnnotatedElement.java
> --- a/src/share/classes/java/lang/reflect/AnnotatedElement.java Tue Jul
> 09 16:00:41 2013 +0100
> +++ b/src/share/classes/java/lang/reflect/AnnotatedElement.java Tue Jul
> 09 14:40:02 2013 -0700
> @@ -43,38 +43,62 @@
>    * through" a container annotation (JLS 9.7) which was generated at
>    * compile-time to wrap multiple annotations of the argument type.
>    *
> - * <p>The terms <em>directly present</em> and <em>present</em> are used
> - * throughout this interface to describe precisely which annotations are
> - * returned by methods:
> + * <p>The terms <em>directly present</em>, <em>directly present</em>,
> + * <em>present</em>, and <em>associated</em> are used throughout this
> + * interface to describe precisely which annotations are returned by
> + * methods:
>    *
>    * <ul>
> - * <li>An annotation A is <em>directly present</em> on an element E if
> E is
> - * associated with a RuntimeVisibleAnnotations or
> - * RuntimeVisibleParameterAnnotations attribute, and:
> + *
> + * <li> An annotation <i>A</i> is <em>directly present</em> on an
> + * element <i>E</i> if <i>E</i> has a {@code
> + * RuntimeVisibleAnnotations} or {@code
> + * RuntimeVisibleParameterAnnotations} or {@code
> + * RuntimeVisibleTypeAnnotations} attribute, and the attribute
> + * contains <i>A</i>.
> + *
> + * <li>An annotation <i>A</i> is <em>indirectly present</em> on an
> + * element <i>E</i> if <i>E</i> has a {@code RuntimeVisibleAnnotations} or
> + * {@code RuntimeVisibleParameterAnnotations} or {@code
> RuntimeVisibleTypeAnnotations}
> + * attribute, and <i>A</i> 's type is repeatable, and the attribute
> contains
> + * exactly one annotation whose value element contains <i>A</i> and whose
> + * type is the containing annotation type of <i>A</i> 's type.
> + *
> + * <li>An annotation <i>A</i> is present on an element <i>E</i> if either:
>    *
>    * <ul>
> - * <li>for an invocation of {@code get[Declared]Annotation(Class<T>)} or
> - * {@code get[Declared]Annotations()}, the attribute contains A.
>    *
> - * <li>for an invocation of {@code
> get[Declared]AnnotationsByType(Class<T>)}, the
> - * attribute either contains A or, if the type of A is repeatable,
> contains
> - * exactly one annotation whose value element contains A and whose type
> is the
> - * containing annotation type of A's type (JLS 9.6).
> + * <li><i>A</i> is directly present on <i>E</i>; or
> + *
> + * <li>No annotation of <i>A</i> 's type is directly present on
> + * <i>E</i>, and <i>E</i> is a class, and <i>A</i> 's type is
> + * inheritable, and <i>A</i> is present on the superclass of <i>E</i>.
> + *
>    * </ul>
>    *
> - * <p>
> - * <li>An annotation A is <em>present</em> on an element E if either:
> + * <li>An annotation <i>A</i> is <em>associated</em> with an element
> <i>E</i>
> + * if either:
>    *
>    * <ul>
> - * <li>A is <em>directly present</em> on E; or
>    *
> - * <li>A is not <em>directly present</em> on E, and E is a class, and
> A's type
> - * is inheritable (JLS 9.6.3.3), and A is <em>present</em> on the
> superclass of
> - * E.
> + * <li><i>A</i> is directly or indirectly present on <i>E</i>; or
> + *
> + * <li>No annotation of <i>A</i> 's type is directly or indirectly
> + * present on <i>E</i>, and <i>E</i> is a class, and <i>A</i>'s type
> + * is inheritable, and <i>A</i> is associated with the superclass of
> + * <i>E</i>.
> + *
>    * </ul>
>    *
>    * </ul>
>    *
> + * For an invocation of {@code get[Declared]AnnotationsByType( Class <
> + * T >)}, the order of annotations which are directly or indirectly
> + * present on an element <i>E</i> is computed as if indirectly present
> + * annotations on <i>E</i> are directly present on <i>E</i> in place
> + * of their container annotation, in the order in which they appear in
> + * the value element of the container annotation.
> +
>    * <p>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
> @@ -85,10 +109,11 @@
>    * a {@link EnumConstantNotPresentException} if the enum constant in the
>    * annotation is no longer present in the enum type.
>    *
> - * <p>Attempting to read annotations of a repeatable annotation type T
> - * that are contained in an annotation whose type is not, in fact, the
> - * containing annotation type of T, will result in an {@link
> - * AnnotationFormatError}.
> + * <p>If an annotation type <i>T</i> is (meta-)annotated with an
> + * {@code @Repeatable} annotation whose value element indicates a type
> + * <i>TC</i>, but <i>TC</i> does not declare a {@code value()} method
> + * with a return type of <i>T</i>{@code []}, then an exception of type
> + * {@link java.lang.annotation.AnnotationFormatError} is thrown.
>    *
>    * <p>Finally, attempting to read a member whose definition has evolved
>    * incompatibly will result in a {@link
> @@ -106,7 +131,7 @@
>   public interface AnnotatedElement {
>       /**
>        * Returns true if an annotation for the specified type
> -     * is present on this element, else false.  This method
> +     * is <em>present</em> on this element, else false.  This method
>        * is designed primarily for convenient access to marker annotations.
>        *
>        * <p>The truth value returned by this method is equivalent to:
> @@ -128,7 +153,7 @@
>
>      /**
>        * Returns this element's annotation for the specified type if
> -     * such an annotation is present, else null.
> +     * such an annotation is <em>present</em>, else null.
>        *
>        * @param <T> the type of the annotation to query for and return
> if present
>        * @param annotationClass the Class object corresponding to the
> @@ -141,9 +166,9 @@
>       <T extends Annotation> T getAnnotation(Class<T> annotationClass);
>
>       /**
> -     * Returns annotations that are <em>present</em> on this element.
> +     * Returns annotations that are <em>associated</em> with this element.
>        *
> -     * If there are no annotations <em>present</em> on this element,
> the return
> +     * If there are no annotations <em>associated</em> with this
> element, the return
>        * value is an array of length 0.
>        *
>        * The difference between this method and {@link
> #getAnnotation(Class)}
> @@ -159,7 +184,7 @@
>        * @param annotationClass the Class object corresponding to the
>        *        annotation type
>        * @return all this element's annotations for the specified
> annotation type if
> -     *     present on this element, else an array of length zero
> +     *     associated with this element, else an array of length zero
>        * @throws NullPointerException if the given annotation class is null
>        * @since 1.8
>        */
> @@ -181,16 +206,16 @@
>
>       /**
>        * Returns this element's annotation for the specified type if
> -     * such an annotation is present, else null.
> +     * such an annotation is <em>directly present</em>, else null.
>        *
>        * This method ignores inherited annotations. (Returns null if no
>        * annotations are directly present on this element.)
>        *
> -     * @param <T> the type of the annotation to query for and return if
> present
> +     * @param <T> the type of the annotation to query for and return if
> directly present
>        * @param annotationClass the Class object corresponding to the
>        *        annotation type
>        * @return this element's annotation for the specified annotation
> type if
> -     *     present on this element, else null
> +     *     directly present on this element, else null
>        * @throws NullPointerException if the given annotation class is null
>        * @since 1.8
>        */
> @@ -217,7 +242,7 @@
>        * @param annotationClass the Class object corresponding to the
>        *        annotation type
>        * @return all this element's annotations for the specified
> annotation type if
> -     *     present on this element, else an array of length zero
> +     *     directly present on this element, else an array of length zero
>        * @throws NullPointerException if the given annotation class is null
>        * @since 1.8
>        */
>