Proposed incorporation of specification change for present/directly present/etc. terminology into javax.lang.model

[Alex Buckley]

1. "directly present" says the annotation @Foo(x=1) is directly present 
if any annotation of type Foo is present. (Assuming an int element x in 
type Foo.) So is @Foo(x=2). And @Foo(x=3). And @Foo(x=4). And so on. I 
know we only have type-based lookup for annotations today, but we should 
not open the door to weirdo answers for "tell me all the annotations of 
type Foo which are directly present". Try this:

-- 
An annotation A is directly present on a construct C if either:

- A is explicitly or implicitly declared as applying to the source code 
representation of C; or
- A appears in the executable output corresponding to C, such as in the 
RuntimeVisibleAnnotations attribute of a class file.
-- 

(The "declared" in "explicitly or implicitly declared" does not pertain 
to solely declaration annotations. If you repeat a type annotation, then 
the type annotations' container annotation will be an implicitly 
declared type annotation.)

2. The "present" and "associated" definitions both use the type AT but 
it's not bound to anything.

3. The "indirectly present" definition also has AT spring out of 
nowhere, but also it's important to say "... if both of the following 
conditions are true:" rather than just "... if:" because it's easy to 
assume the bullet point are alternatives as in the other three definitions.

Alex

On 5/15/2013 11:22 PM, Joe Darcy wrote:
> Hello,
>
> I've been working to update the javadoc specification in
> javax.lang.model.* with the new present / directly present / etc.
> terminology from the latest 8misc.pdf file.
>
> Proposed patch is below.
>
> Full webrev of the change available from
>
>      http://cr.openjdk.java.net/~darcy/8010680.1/
>
> Thanks,
>
> -Joe
>
> --- a/src/share/classes/javax/lang/model/AnnotatedConstruct.java Wed May
> 15 10:39:26 2013 -0700
> +++ b/src/share/classes/javax/lang/model/AnnotatedConstruct.java Wed May
> 15 23:18:28 2013 -0700
> @@ -39,35 +39,64 @@
>    * are on a <em>declaration</em>, whereas annotations on a type are on
>    * a specific <em>use</em> of a type name.
>    *
> - * The terms <em>directly present</em> and <em>present</em> are used
> + * The terms <em>directly present</em>, <em>present</em>,
> + * <em>indirectly present</em>, and <em>associated </em> are used
>    * throughout this interface to describe precisely which annotations
> - * are returned by methods:
> + * are returned by the methods defined herein.
>    *
> - * <p>An annotation <i>A</i> is <em>directly present</em> on a
> - * construct <i>E</i> if <i>E</i> is annotated, and:
> + * <p>An annotation <i>A</i> of annotation type <i>AT</i> is
> + * <em>directly present</em> on a construct <i>C</i> if either:
>    *
>    * <ul>
>    *
> - * <li> for an invocation of {@code getAnnotation(Class<T>)} or
> - * {@code getAnnotationMirrors()}, <i>E</i>'s annotations contain
> <i>A</i>.
> + * <li>Exactly one annotation of type <i>AT</i> appears in the source
> + * code representation for <i>C</i>.
>    *
> - * <li> for an invocation of {@code getAnnotationsByType(Class<T>)},
> - * <i>E</i>'s annotations either contain <i>A</i> or, if the type of
> - * <i>A</i> is repeatable, contain 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><i>AT</i> is the containing annotation type for a repeatable
> + * annotation type <i>T</i> and the source code for <i>C</i> has
> + * multiple annotations of type <i>T</i>.
> + *
> + * <li> A representation of <i>A</i> appears in the executable output
> + * for <i>C</i>, such as the {@code RuntimeVisibleAnnotations} or
> + * {@code RuntimeVisibleParameterAnnotations} attributes of a class
> + * file.
>    *
>    * </ul>
>    *
> - * <p>An annotation A is <em>present</em> on a construct E if either:
> + * <p>An annotation <i>A</i> is <em>present</em> on a
> + * construct <i>C</i> if either:
> + * <ul>
> + *
> + * <li><i>A</i> is directly present on <i>C</i>.
> + *
> + * <li>No annotation of type <i>AT</i> is directly present on
> + * <i>C</i>, and <i>C</i> is a class and <i>AT</i> is inheritable
> + * and <i>A</i> is present on the superclass of <i>C</i>.
> + *
> + * </ul>
> + *
> + * An annotation <i>A</i> is <em>indirectly present</em> on a construct
> + * <i>C</i> if:
>    *
>    * <ul>
> - *  <li> <i>A</i> is <em>directly present</em> on <i>E</i>; or
>    *
> - *  <li> <i>A</i> is not <em>directly present</em> on <i>E</i>, and
> - *  <i>E</i> is an element representing a class, and <i>A</i>'s type
> - *  is inheritable, and <i>A</i> is <em>present</em> on the element
> - *  representing the superclass of <i>E</i>.
> + * <li><i>AT</i> is a repeatable annotation type with a containing
> annotation type <i>ATC</i>.
> + *
> + * <li>An annotation of type <i>ATC</i> is directly present on <i>C</i>.
> + *
> + * </ul>
> + *
> + * An annotation <i>A</i> is <em>associated</em> with a construct
> + * <i>C</i> if either:
> + *
> + * <ul>
> + *
> + * <li> <i>A</i> is directly or indirectly present on <i>C</i>.
> + *
> + * <li> No annotation of type <i>AT</i> is directly or indirectly
> + * present on <i>C</i>, <i>C</i> is a class, and <i>AT</i> is
> + * inheritable, and <i>AT</i> is associated with the superclass of
> + * <i>C</i>.
>    *
>    * </ul>
>    *
> @@ -86,9 +115,8 @@
>       List<? extends AnnotationMirror> getAnnotationMirrors();
>
>       /**
> -     * Returns this construct's annotation of the
> -     * specified type if such an annotation is <em>present</em>, else
> {@code
> -     * null}.
> +     * Returns this construct's annotation of the specified type if
> +     * such an annotation is <em>present</em>, else {@code null}.
>        *
>        * <p> The annotation returned by this method could contain an
> element
>        * whose value is of type {@code Class}.
> @@ -118,9 +146,8 @@
>        * @param <A>  the annotation type
>        * @param annotationType  the {@code Class} object corresponding to
>        *          the annotation type
> -     * @return this element's or type use's annotation for the
> -     * specified annotation type if present on this element, else
> -     * {@code null}
> +     * @return this construct's annotation for the specified
> +     * annotation type if present, else {@code null}
>        *
>        * @see #getAnnotationMirrors()
>        * @see java.lang.reflect.AnnotatedElement#getAnnotation
> @@ -134,10 +161,10 @@
>       <A extends Annotation> A getAnnotation(Class<A> annotationType);
>
>       /**
> -     * Returns annotations that are <em>present</em> on this construct.
> +     * Returns annotations that are <em>associated</em> with this
> construct.
>        *
> -     * If there are no annotations <em>present</em> on this construct,
> -     * the return value is an array of length 0.
> +     * If there are no annotations associated with this construct, the
> +     * return value is an array of length 0.
>        *
>        * The difference between this method and {@link
> #getAnnotation(Class)}
>        * is that this method detects if its argument is a <em>repeatable
> @@ -172,8 +199,8 @@
>        * @param <A>  the annotation type
>        * @param annotationType  the {@code Class} object corresponding to
>        *          the annotation type
> -     * @return this element's annotations for the specified annotation
> -     *         type if present on this element, else an empty array
> +     * @return this construct's annotations for the specified annotation
> +     *         type if present on this construct, else an empty array
>        *
>        * @see #getAnnotationMirrors()
>        * @see #getAnnotation(java.lang.Class)
> diff -r 445b8b5ae9f4 src/share/classes/javax/lang/model/util/Elements.java
> --- a/src/share/classes/javax/lang/model/util/Elements.java    Wed May
> 15 10:39:26 2013 -0700
> +++ b/src/share/classes/javax/lang/model/util/Elements.java    Wed May
> 15 23:18:28 2013 -0700
> @@ -143,12 +143,13 @@
>       List<? extends Element> getAllMembers(TypeElement type);
>
>       /**
> -     * Returns all annotations of an element, whether
> -     * inherited or directly present.
> +     * Returns all annotations <i>present</i> on an element, whether
> +     * directly present or present via inheritance.
>        *
>        * @param e  the element being examined
>        * @return all annotations of the element
>        * @see Element#getAnnotationMirrors
> +     * @see javax.lang.model.AnnotatedConstruct
>        */
>       List<? extends AnnotationMirror> getAllAnnotationMirrors(Element e);
>
>