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

[Alex Buckley]

- "directly present" and "present" are OK.

- "indirectly present" still doesn't bind A strongly enough ... it's 
necessary but not sufficient that an annotation of type ATC is directly 
present on C ... the sufficient clause is that the ATC-typed annotation 
must have a value element which contains A.

- "associated" is almost OK except for a type error: the final clause 
must be "and <i>A</i> is associated with the superclass of <i>C</i>." 
(The domain of "associated" is annotations, not annotation types, so AT 
is never associated with anything.)

Alex

On 5/20/2013 10:35 PM, Joe Darcy wrote:
> Hello,
>
> On 05/16/2013 11:56 AM, Alex Buckley wrote:
>> 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.
>
> Reworked portions of the patch below; full webrev at
>
>      http://cr.openjdk.java.net/~darcy/8010680.2
>
> Thanks,
>
> -Joe
>
> --- a/src/share/classes/javax/lang/model/AnnotatedConstruct.java Fri May
> 17 13:48:41 2013 -0700
> +++ b/src/share/classes/javax/lang/model/AnnotatedConstruct.java Mon May
> 20 22:34:23 2013 -0700
> @@ -39,35 +39,72 @@
>    * 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>In the definitions below, an annotation <i>A</i> has an
> + * annotation type <i>AT</i>. If <i>AT</i> is a repeatable annotation
> + * type, the type of the containing annotation is <i>ATC</i>.
> + *
> + * <p>Annotation <i>A</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><i>A</i> is explicitly or implicitly declared as applying to
> + * the source code representation of <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.
> + * <p>Typically, if exactly one annotation of type <i>AT</i> appears in
> + * the source code of representation of <i>C</i>, then <i>A</i> is
> + * explicitly declared as applying to <i>C</i>.
> + *
> + * If there are multiple annotations of type <i>AT</i> present on
> + * <i>C</i>, then if <i>AT</i> is repeatable annotation type, an
> + * annotation of type <i>ATC</i> is implicitly declared on <i>C</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 both:
>    *
>    * <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>
>    *
>
>
>>
>> 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
>