FYI, JSR 308 and the annotation processing discovery process

[Alex Buckley]

On 3/28/2013 10:39 PM, Joe Darcy wrote:
> FYI, as the JSR 269 maintenance lead, besides updating the
> javax.lang.model.* API to handle new-in-Java-SE-8 features, I'm not
> looking at updating the javax.annotation.processing API to deal with
> those new annotation-related features too.

"not looking"? Surely "now looking".

> "The tool uses a discovery process to find annotation processors and
> decide whether or not they should be run. [...] Which processors the
> tool asks to run is a function of what annotations are present on the
> root elements, what annotation types a processor processes, and whether
> or not a processor claims the annotations it processes. [...] For a
> given round, the tool computes the set of annotation types on the root
> elements. If there is at least one annotation type present, as
> processors claim annotation types, they are removed from the set of
> unmatched annotations."

Close reading of the above paragraph reveals that:

- a processor _claims_ annotation types
- a processor _claims_ annotations
- a processor _processes_ annotations
- from a set of annotations, it is possible to remove annotation _types_

I contend there is at least one kind error going on here.

> To this, I plan to add a paragraph explaining how type annotations do
> not interact with the this discovery process; something like:
>
> "<p>An annotation type is considered present if there is at least one
> annotation of that type on a declaration enclosed within the root
> elements of a round. For this purpose, a type parameter is considered
> to be enclosed by its generic element. Annotations on type uses are
> <em>not</em> considered as part of the computation.

There is quite a phase shift between the "For this purpose" sentence and 
the type uses sentence. I think a new paragraph is warranted: 
"Annotations on type uses are ignored when computing the set of 
annotation types present on the root elements."

> For the purposes of JSR 308:
>
> * Declaration annotations on type parameters are included in discovery
> * TYPE_USE annotations are *not* included as part of discovery

You mean to put "For the purposes of JSR 308" into the SE 8 API spec? 
That would be wrong, as a JSR number is pure administration and the API 
spec should deal only in features.

For the bullet points, beware: an annotation whose type targets TYPE_USE 
can appear on a type declaration or a type parameter declaration. Surely 
you want such an annotation on class Foo's declaration to be discovered. 
Do you mean:

- Annotations on type parameter declarations are included in discovery.
- Annotations on type uses are not included in discovery.

Alex