src/share/classes/javax/annotation/processing/Processor.java

@@ -1,7 +1,7 @@
 /*
- * 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
  * under the terms of the GNU General Public License version 2 only, as
  * published by the Free Software Foundation.  Oracle designates this

@@ -24,10 +24,11 @@
  */
 
 package javax.annotation.processing;
 
 import java.util.Set;
+import javax.lang.model.util.Elements;
 import javax.lang.model.element.*;
 import javax.lang.model.SourceVersion;
 
 /**
  * The interface for an annotation processor.

@@ -104,10 +105,27 @@
  * there are no annotation types present, annotation processing still
  * occurs but only <i>universal processors</i> which support
  * processing {@code "*"} can claim the (empty) set of annotation
  * types.
  *
+ * <p>An annotation type is considered present if there is an
+ * 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 {@linkplain
+ * TypeParameter#getGenericElement generic element}. Annotations on
+ * {@linkplain ElementType#TYPE_USE type uses} are <em>not</em>
+ * considered as part of the computation. To be present, an annotation
+ * must be returnable by {@link Elements#getAllAnnotationMirrors()},
+ * that is, the annotation must be present on the declaration of the
+ * element or present via inheritance. An annotation is <em>not</em>
+ * considered present by virtue of being wrapped by a container
+ * annotation. Therefore, 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}.
+ *
  * <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
  * checks should return {@code false} so as to not prevent other such
  * checkers from being able to run.