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 not 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. Clarified intention. > > 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. This is compensating for a design but in the initial JSR 269 where type parameters were not enclosed by their declaring method/constructor or type. > > 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 not 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 ...". > Reworded. Thanks, -Joe diff -r 5c548a8542b8 src/share/classes/javax/annotation/processing/Processor.java --- a/src/share/classes/javax/annotation/processing/Processor.java Thu Jun 27 17:45:56 2013 -0400 +++ b/src/share/classes/javax/annotation/processing/Processor.java Thu Jun 27 22:59:40 2013 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -26,6 +26,8 @@ package javax.annotation.processing; import java.util.Set; +import javax.lang.model.util.Elements; +import javax.lang.model.AnnotatedConstruct; import javax.lang.model.element.*; import javax.lang.model.SourceVersion; @@ -88,11 +90,12 @@ * 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 {@linkplain AnnotatedConstruct present} + * on the {@linkplain * RoundEnvironment#getRootElements root elements}, what {@linkplain * #getSupportedAnnotationTypes annotation types a processor * processes}, and whether or not a processor {@linkplain #process - * claims the annotations it processes}. A processor will be asked to + * 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. * @@ -106,6 +109,32 @@ * processing {@code "*"} can claim the (empty) set of annotation * types. * + *
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}, as opposed to annotations on + * elements, are not considered as part of the + * computation. For this purpose, a type parameter is considered to be + * enclosed by its {@linkplain TypeParameter#getGenericElement generic + * element}. + * + *
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 + * not 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 repeatable annotation + * type and its containing annotation type in the set of {@linkplain + * #getSupportedAnnotationTypes() supported annotation types} of a + * processor. + * *
Note that if a processor supports {@code "*"} and returns {@code * true}, all annotations are claimed. Therefore, a universal * processor being used to, for example, implement additional validity @@ -257,10 +286,10 @@ /** * 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. If {@code - * true} is returned, the annotations are claimed and subsequent + * these annotation types are claimed by this processor. If {@code + * true} is returned, the annotation types are claimed and subsequent * processors will not be asked to process them; if {@code false} - * is returned, the annotations are unclaimed and subsequent + * is returned, the annotation types are unclaimed and subsequent * processors may be asked to process them. A processor may * always return the same boolean value or may vary the result * based on chosen criteria. @@ -271,7 +300,7 @@ * * @param annotations the annotation types requested to be processed * @param roundEnv environment for information about the current and prior round - * @return whether or not the set of annotations are claimed by this processor + * @return whether or not the set of annotation types are claimed by this processor */ boolean process(Set annotations, RoundEnvironment roundEnv); diff -r 5c548a8542b8 src/share/classes/javax/annotation/processing/AbstractProcessor.java --- a/src/share/classes/javax/annotation/processing/AbstractProcessor.java Thu Jun 27 17:45:56 2013 -0400 +++ b/src/share/classes/javax/annotation/processing/AbstractProcessor.java Thu Jun 27 23:00:00 2013 -0700 @@ -38,7 +38,7 @@ * superclass for most concrete annotation processors. This class * examines annotation values to compute the {@linkplain * #getSupportedOptions options}, {@linkplain - * #getSupportedAnnotationTypes annotations}, and {@linkplain + * #getSupportedAnnotationTypes annotation types}, and {@linkplain * #getSupportedSourceVersion source version} supported by its * subtypes. * From alex.buckley at oracle.com Fri Jun 28 12:00:13 2013 From: alex.buckley at oracle.com (Alex Buckley) Date: Fri, 28 Jun 2013 12:00:13 -0700 Subject: FYI, JSR 308 and the annotation processing discovery process In-Reply-To: <51CD2675.4080202@oracle.com> References: <5155291F.2050907@oracle.com> <51561161.8030207@oracle.com> <515A5C52.50907@oracle.com> <519DA40C.9090703@oracle.com> <519E6721.80906@oracle.com> <51CD2675.4080202@oracle.com> Message-ID: <51CDDD3D.5000809@oracle.com> 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 universal processors 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. 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 new para at line 121 is good. Alex P.S. I was thinking about terminology recently. Annotation types ought to have been called "schema types" to draw a bright line between the declaration of a thing (the type) and a use of the thing (the annotation). Then, annotation is to schema as object is to class. On 6/27/2013 11:00 PM, Joe Darcy wrote: > Hello, > > Swapping discussion of this specification back in so it can be brought > to a conclusion. > > Diffs of changed specification text are below. FYI, full webrev, > including supporting implementation changes, viewable at: > > http://cr.openjdk.java.net/~darcy/7162089.3/ > > On 05/23/2013 11:59 AM, Alex Buckley wrote: >> 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 {@linkplain AnnotatedConstruct >>> present} >>> + * 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 full situation is a bit more complicated. There is a set of > annotation types. The processing environment keeps looking for > processors to process them until the set is empty or until there are no > processors to ask. If a processor claims annotation (types), they are > removed from the set of unmatched annotation types. Therefore, the types > of annotation a processor is asked to process depends on the annotation > types claimed by processors earlier on the search path. > >> >> 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." > > I've gone through and changed the wording of Processor and > AbstractProcessor to use "annotation types" consistently. > >> >> 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... >> >>> + *
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 not 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. > > Clarified intention. > >> >> 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. > > This is compensating for a design but in the initial JSR 269 where type > parameters were not enclosed by their declaring method/constructor or type. > >> >> 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 not 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 ...". >> > > Reworded. > > Thanks, > > -Joe > > diff -r 5c548a8542b8 > src/share/classes/javax/annotation/processing/Processor.java > --- a/src/share/classes/javax/annotation/processing/Processor.java Thu > Jun 27 17:45:56 2013 -0400 > +++ b/src/share/classes/javax/annotation/processing/Processor.java Thu > Jun 27 22:59:40 2013 -0700 > @@ -1,5 +1,5 @@ > /* > - * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights > reserved. > + * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights > reserved. > * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. > * > * This code is free software; you can redistribute it and/or modify it > @@ -26,6 +26,8 @@ > package javax.annotation.processing; > > import java.util.Set; > +import javax.lang.model.util.Elements; > +import javax.lang.model.AnnotatedConstruct; > import javax.lang.model.element.*; > import javax.lang.model.SourceVersion; > > @@ -88,11 +90,12 @@ > * 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 {@linkplain AnnotatedConstruct > present} > + * on the {@linkplain > * RoundEnvironment#getRootElements root elements}, what {@linkplain > * #getSupportedAnnotationTypes annotation types a processor > * processes}, and whether or not a processor {@linkplain #process > - * claims the annotations it processes}. A processor will be asked to > + * 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. > * > @@ -106,6 +109,32 @@ > * processing {@code "*"} can claim the (empty) set of annotation > * types. > * > + *
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}, as opposed to annotations on > + * elements, are not considered as part of the > + * computation. For this purpose, a type parameter is considered to be > + * enclosed by its {@linkplain TypeParameter#getGenericElement generic > + * element}. > + * > + *
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 > + * not 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 repeatable annotation > + * type and its containing annotation type in the set of {@linkplain > + * #getSupportedAnnotationTypes() supported annotation types} of a > + * processor. > + * > *
Note that if a processor supports {@code "*"} and returns {@code > * true}, all annotations are claimed. Therefore, a universal > * processor being used to, for example, implement additional validity > @@ -257,10 +286,10 @@ > /** > * 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. If {@code > - * true} is returned, the annotations are claimed and subsequent > + * these annotation types are claimed by this processor. If {@code > + * true} is returned, the annotation types are claimed and subsequent > * processors will not be asked to process them; if {@code false} > - * is returned, the annotations are unclaimed and subsequent > + * is returned, the annotation types are unclaimed and subsequent > * processors may be asked to process them. A processor may > * always return the same boolean value or may vary the result > * based on chosen criteria. > @@ -271,7 +300,7 @@ > * > * @param annotations the annotation types requested to be processed > * @param roundEnv environment for information about the current > and prior round > - * @return whether or not the set of annotations are claimed by > this processor > + * @return whether or not the set of annotation types are claimed > by this processor > */ > boolean process(Set annotations, > RoundEnvironment roundEnv); > > diff -r 5c548a8542b8 > src/share/classes/javax/annotation/processing/AbstractProcessor.java > --- > a/src/share/classes/javax/annotation/processing/AbstractProcessor.java > Thu Jun 27 17:45:56 2013 -0400 > +++ > b/src/share/classes/javax/annotation/processing/AbstractProcessor.java > Thu Jun 27 23:00:00 2013 -0700 > @@ -38,7 +38,7 @@ > * superclass for most concrete annotation processors. This class > * examines annotation values to compute the {@linkplain > * #getSupportedOptions options}, {@linkplain > - * #getSupportedAnnotationTypes annotations}, and {@linkplain > + * #getSupportedAnnotationTypes annotation types}, and {@linkplain > * #getSupportedSourceVersion source version} supported by its > * subtypes. > * > From joe.darcy at oracle.com Fri Jun 28 16:25:54 2013 From: joe.darcy at oracle.com (Joe Darcy) Date: Fri, 28 Jun 2013 16:25:54 -0700 Subject: FYI, JSR 308 and the annotation processing discovery process In-Reply-To: <51CDDD3D.5000809@oracle.com> References: <5155291F.2050907@oracle.com> <51561161.8030207@oracle.com> <515A5C52.50907@oracle.com> <519DA40C.9090703@oracle.com> <519E6721.80906@oracle.com> <51CD2675.4080202@oracle.com> <51CDDD3D.5000809@oracle.com> Message-ID: <51CE1B82.5070809@oracle.com> 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 universal processors > 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 {@linkplain AnnotatedConstruct present} * 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 universal processors 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: *
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 not 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 From alex.buckley at oracle.com Fri Jun 28 19:42:37 2013 From: alex.buckley at oracle.com (Alex Buckley) Date: Fri, 28 Jun 2013 19:42:37 -0700 (PDT) Subject: FYI, JSR 308 and the annotation processing discovery process Message-ID: <45350d63-1de6-410f-83e0-4028bfa44f69@default> OK, now I got it (annotation-type-present). All looks good. I'm still inclined to link up the end of annotation-type-present paragraph with the beginning though: "Annotations on {@linkplain ElementType#TYPE_USE type uses}, as opposed to annotations on elements, are ignored when computing if an annotation type is present." Alex ----- Original Message ----- From: joe.darcy at oracle.com To: alex.buckley at oracle.com Cc: type-annotations-spec-comments at openjdk.java.net Sent: Friday, June 28, 2013 4:25:55 PM GMT -08:00 US/Canada Pacific Subject: Re: FYI, JSR 308 and the annotation processing discovery process 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 universal processors > 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 {@linkplain AnnotatedConstruct present} * 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 universal processors 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: *
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 not 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