1.1 --- a/src/share/classes/javax/annotation/processing/Processor.java Mon Jul 01 14:57:03 2013 +0100
1.2 +++ b/src/share/classes/javax/annotation/processing/Processor.java Mon Jul 01 11:58:45 2013 -0700
1.3 @@ -1,5 +1,5 @@
1.4 /*
1.5 - * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
1.6 + * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
1.7 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.8 *
1.9 * This code is free software; you can redistribute it and/or modify it
1.10 @@ -26,6 +26,8 @@
1.11 package javax.annotation.processing;
1.12
1.13 import java.util.Set;
1.14 +import javax.lang.model.util.Elements;
1.15 +import javax.lang.model.AnnotatedConstruct;
1.16 import javax.lang.model.element.*;
1.17 import javax.lang.model.SourceVersion;
1.18
1.19 @@ -88,23 +90,52 @@
1.20 * configuration mechanisms, such as command line options; for
1.21 * details, refer to the particular tool's documentation. Which
1.22 * processors the tool asks to {@linkplain #process run} is a function
1.23 - * of what annotations are present on the {@linkplain
1.24 + * of the types of the annotations <em>{@linkplain AnnotatedConstruct present}</em>
1.25 + * on the {@linkplain
1.26 * RoundEnvironment#getRootElements root elements}, what {@linkplain
1.27 * #getSupportedAnnotationTypes annotation types a processor
1.28 - * processes}, and whether or not a processor {@linkplain #process
1.29 - * claims the annotations it processes}. A processor will be asked to
1.30 + * supports}, and whether or not a processor {@linkplain #process
1.31 + * claims the annotation types it processes}. A processor will be asked to
1.32 * process a subset of the annotation types it supports, possibly an
1.33 * empty set.
1.34 *
1.35 - * For a given round, the tool computes the set of annotation types on
1.36 - * the root elements. If there is at least one annotation type
1.37 - * present, as processors claim annotation types, they are removed
1.38 - * from the set of unmatched annotations. When the set is empty or no
1.39 - * more processors are available, the round has run to completion. If
1.40 + * For a given round, the tool computes the set of annotation types
1.41 + * that are present on the elements enclosed within the root elements.
1.42 + * If there is at least one annotation type present, then as
1.43 + * processors claim annotation types, they are removed from the set of
1.44 + * unmatched annotation types. When the set is empty or no more
1.45 + * processors are available, the round has run to completion. If
1.46 * there are no annotation types present, annotation processing still
1.47 * occurs but only <i>universal processors</i> which support
1.48 - * processing {@code "*"} can claim the (empty) set of annotation
1.49 - * types.
1.50 + * processing all annotation types, {@code "*"}, can claim the (empty)
1.51 + * set of annotation types.
1.52 + *
1.53 + * <p>An annotation type is considered present if there is at least
1.54 + * one annotation of that type present on an element enclosed within
1.55 + * the root elements of a round. For this purpose, a type parameter is
1.56 + * considered to be enclosed by its {@linkplain
1.57 + * TypeParameterElement#getGenericElement generic
1.58 + * element}. Annotations on {@linkplain
1.59 + * java.lang.annotation.ElementType#TYPE_USE type uses}, as opposed to
1.60 + * annotations on elements, are ignored when computing whether or not
1.61 + * an annotation type is present.
1.62 + *
1.63 + * <p>An annotation is present if it meets the definition of being
1.64 + * present given in {@link AnnotatedConstruct}. In brief, an
1.65 + * annotation is considered present for the purposes of discovery if
1.66 + * it is directly present or present via inheritance. An annotation is
1.67 + * <em>not</em> considered present by virtue of being wrapped by a
1.68 + * container annotation. Operationally, this is equivalent to an
1.69 + * annotation being present on an element if and only if it would be
1.70 + * included in the results of {@link
1.71 + * Elements#getAllAnnotationMirrors(Element)} called on that element. Since
1.72 + * annotations inside container annotations are not considered
1.73 + * present, to properly process {@linkplain
1.74 + * java.lang.annotation.Repeatable repeatable annotation types},
1.75 + * processors are advised to include both the repeatable annotation
1.76 + * type and its containing annotation type in the set of {@linkplain
1.77 + * #getSupportedAnnotationTypes() supported annotation types} of a
1.78 + * processor.
1.79 *
1.80 * <p>Note that if a processor supports {@code "*"} and returns {@code
1.81 * true}, all annotations are claimed. Therefore, a universal
1.82 @@ -257,10 +288,10 @@
1.83 /**
1.84 * Processes a set of annotation types on type elements
1.85 * originating from the prior round and returns whether or not
1.86 - * these annotations are claimed by this processor. If {@code
1.87 - * true} is returned, the annotations are claimed and subsequent
1.88 + * these annotation types are claimed by this processor. If {@code
1.89 + * true} is returned, the annotation types are claimed and subsequent
1.90 * processors will not be asked to process them; if {@code false}
1.91 - * is returned, the annotations are unclaimed and subsequent
1.92 + * is returned, the annotation types are unclaimed and subsequent
1.93 * processors may be asked to process them. A processor may
1.94 * always return the same boolean value or may vary the result
1.95 * based on chosen criteria.
1.96 @@ -271,7 +302,7 @@
1.97 *
1.98 * @param annotations the annotation types requested to be processed
1.99 * @param roundEnv environment for information about the current and prior round
1.100 - * @return whether or not the set of annotations are claimed by this processor
1.101 + * @return whether or not the set of annotation types are claimed by this processor
1.102 */
1.103 boolean process(Set<? extends TypeElement> annotations,
1.104 RoundEnvironment roundEnv);
