FYI, JSR 308 and the annotation processing discovery process

[Alex Buckley]

Thanks very much Joe. Some distressingly tricky stuff below:

On 5/22/2013 10:07 PM, Joe Darcy wrote:
> @@ -88,7 +90,8 @@
>    * configuration mechanisms, such as command line options; for
>    * details, refer to the particular tool's documentation.  Which
>    * processors the tool asks to {@linkplain #process run} is a function
> - * of what annotations are present on the {@linkplain
> + * of the types of the annotations <em>{@linkplain AnnotatedConstruct
> present}</em>
> + * on the {@linkplain
>    * RoundEnvironment#getRootElements root elements}, what {@linkplain
>    * #getSupportedAnnotationTypes annotation types a processor
>    * processes}, and whether or not a processor {@linkplain #process
> @@ -106,6 +109,28 @@

It would be clearer and more kind-correct to say:

"Which processors the tool asks to run is a function of i) the types of 
the annotations present on the root elements, ii) the annotation types 
supported by a processor, and iii) the annotation types claimed by a 
processor."

The idea that a processor CLAIMS annotation types comes from line 104. 
And if this is right, Processor#process must be clarified. It takes a 
set of types - great - and returns whether the processor claims all 
annotations of those types. If you intend to draw an equivalence between 
"claiming all annotations of types X and Y" and "claiming the annotation 
types X and Y", please be explicit about it. Right now, the following 
method spec simply does not parse: "Processes a set of ANNOTATION TYPES 
on type elements originating from the prior round and returns whether or 
not THESE ANNOTATIONS are claimed by this processor."

It would also be good to say "(see below)" when line 104 introduces the 
idea of annotation types being present, since the more common concept is 
of annotations being present.

OK, moving to the new text...

> + * <p>An annotation type is considered present if there is at least
> + * one annotation of that type present on an element enclosed within
> + * the root elements of a round.

> + * Annotations on {@linkplain
> + * ElementType#TYPE_USE type uses} are <em>not</em> considered as part
> + * of the computation.

An annotation might be able to target type uses _and_ traditional 
declaration locations. I think you want to ignore annotations which are 
_solely_ interested in targeting type uses. At the same time, remember 
that ElementType.TYPE_USE means "type uses _and_ type declarations and 
type parameter declarations". So, given an annotation type Foo with 
@Target(TYPE_USE) and no other @Target, would @Foo being present on a 
type declaration mean that annotation type Foo is present? The answer 
should be "yes", because the intent of ElementType.TYPE_USE is to 
supersede ElementType.TYPE (no doubt the prior @Target of Foo) and 
previous annotation processors would have processed @Foo on a type 
declaration just fine.

BTW, line 102 should say "the tool computes the set of annotation types 
PRESENT on the root elements."

> + * For this purpose, a type parameter is
> + * considered to be enclosed by its {@linkplain
> + * TypeParameter#getGenericElement generic element}.

Big context switch here from type-oriented stuff to element-oriented. 
Please put it in in TypeParameterElement's spec.

Please have a paragraph break before the "annotation is present" stuff.

> + * An annotation is
> + * present if it meets the definition of being present given in {@link
> + * AnnotatedConstruct}. In brief, an annotation is considered present
> + * for the purposes of discovery if it is directly present or present
> + * via inheritance. An annotation is <em>not</em> considered present
> + * by virtue of being wrapped by a container
> + * annotation. Operationally, this is equivalent to an annotation
> + * being present on an element if and only if it would be included in
> + * the results of {@link Elements#getAllAnnotationMirrors()} called on
> + * that element. Since annotations inside container annotations are
> + * not considered present, to properly process {@linkplain
> + * java.lang.annotation.Repeatable repeatable annotation types},
> + * processors are advised to include both the annotation and its
> + * container in the set of {@linkplain #getSupportedAnnotationTypes()
> + * supported annotation types} of a processor.

This was going great until: "advised to include both the annotation and 
its container in the set of ..." - it should be "include both the 
repeatable annotation type and its containing annotation type in the set 
of ...".

Alex