[type-annos-observers] FYI, JSR 308 and the annotation processing discovery process

[Joe Darcy]

Hello,

On 06/28/2013 12:00 PM, Alex Buckley wrote:
> In Processor:
>
> Line 96 says "what {@linkplain #getSupportedAnnotationTypes annotation 
> types a processor processes}" - you mean "a processor _supports_". 
> Let's strongly distinguish a processor's fixed set of supported types 
> from its changeable set of claimed types. In a similar vein, I might 
> phrase lines 108/109 as "... but only <i>universal processors</i> 
> which support all annotation types ({@code "*"}) can claim ..."
>
> Line 102: correctness: "the tool computes the set of annotation types 
> _that are present_ on the root elements."
>
> Line 104: style: "_then_ as processors claim annotation types"
>
> Lines 105 says "they are removed from the set of unmatched 
> annotations" but you mean annotation types.

Revised paragraphs:

   [...] Which
  * processors the tool asks to {@linkplain #process run} is a function
  * 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
  * supports}, and whether or not a processor {@linkplain #process
  * claims the annotation types it processes}.  A processor will be asked to
  * process a subset of the annotation types it supports, possibly an
  * empty set.
  *
  * For a given round, the tool computes the set of annotation types
  * that are present on the elements enclosed within the root elements.
  * If there is at least one annotation type present, then as
  * processors claim annotation types, they are removed from the set of
  * unmatched annotation types.  When the set is empty or no more
  * processors are available, the round has run to completion.  If
  * there are no annotation types present, annotation processing still
  * occurs but only <i>universal processors</i> which support
  * processing all annotation types, {@code "*"}, can claim the (empty)
  * set of annotation types.

>
> Line 112: First a stylistic comment, then a semantic comment. The 
> paragraph's three assertions are positive / negative / positive, but I 
> think it would flow better to have the two positive assertions first 
> (annotation-type-considered-present + 
> type-parameter-considered-enclosed) and then the negative assertion 
> (annotations-on-type-uses-ignored). Then, semantically, I'm still 
> confused - this paragraph is about _annotation types_ but you say 
> "_Annotations_ on type uses ...". Maybe you want to say: "An 
> annotation type that targets type uses _is considered present_ if at 
> least one annotation of that type appears on an element enclosed 
> within the root elements of a round; annotations on type uses are not 
> considered in this computation."

The distinction I'm trying to draw there is that if an annotation is 
syntactically on a type use as opposed to a declaration, it is outside 
of the scope of what discovery look at. Reordered 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. For this purpose, a type parameter is
  * considered to be enclosed by its {@linkplain
  * TypeParameter#getGenericElement generic element}. Annotations on
  * {@linkplain ElementType#TYPE_USE type uses}, as opposed to
  * annotations on elements, are <em>not</em> considered as part of
  * this computation.

Thanks for the detailed feedback.

I'd like to push the current version (or a minor revision) by July 1.

Cheers,

-Joe