Updates to javax.annotation.processing.Processor for repeating annotations

[Joe Darcy]

Hello,

Now that the new present, directly present, etc. terminology is worked 
out, the time has come to update the specification of the annotation 
processing discovery procedure to take into account repeating 
annotations (and other annotation updates in Java SE 8).

Proposed diff below. Full webrev of proposed specification and 
implementation changes at:

     http://cr.openjdk.java.net/~darcy/7162089.2/

Thanks,

-Joe

@@ -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 @@
   * processing {@code "*"} can claim the (empty) set of annotation
   * types.
   *
+ * <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. 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 <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.
+ *
   * <p>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