# HG changeset patch # User darcy # Date 1363826500 25200 # Node ID c0b12eae2488dd3c7dfb8ef7797ff1cf2c397aa5 # Parent 9f09744e221ab337152f7d0e319210e2078b804b 8010364: Clarify javax.lang.model API for Type Annotations Reviewed-by: jjg, abuckley diff -r 9f09744e221a -r c0b12eae2488 langtools/src/share/classes/javax/lang/model/AnnotatedConstruct.java --- a/langtools/src/share/classes/javax/lang/model/AnnotatedConstruct.java Tue Mar 19 19:16:59 2013 -0700 +++ b/langtools/src/share/classes/javax/lang/model/AnnotatedConstruct.java Wed Mar 20 17:41:40 2013 -0700 @@ -31,29 +31,64 @@ import javax.lang.model.type.*; /** - * Represent a construct that can have annotations. + * Represents a construct that can be annotated. + * + * A construct is either an {@linkplain + * javax.lang.model.element.Element element} or a {@linkplain + * javax.lang.model.type.TypeMirror type}. Annotations on an element + * are on a declaration, whereas annotations on a type are on + * a specific use of a type name. + * + * The terms directly present and present are used + * throughout this interface to describe precisely which annotations + * are returned by methods: + * + *
An annotation A is directly present on a + * construct E if E is annotated, and: + * + *
An annotation A is present on a construct E if either: + * + *
The annotation returned by this method could contain an element
* whose value is of type {@code Class}.
@@ -94,18 +129,19 @@
* @see IncompleteAnnotationException
* @see MirroredTypeException
* @see MirroredTypesException
+ * @jls 9.6.1 Annotation Type Elements
*/
A getAnnotation(Class annotationType);
/**
- * Returns annotations that are present on this element or type use.
+ * Returns annotations that are present on this construct.
*
- * If there are no annotations present on this element or type use,
+ * If there are no annotations present on this construct,
* the return value is an array of length 0.
*
* The difference between this method and {@link #getAnnotation(Class)}
* is that this method detects if its argument is a repeatable
- * annotation type (JLS 9.6), and if so, attempts to find one or more
+ * annotation type, and if so, attempts to find one or more
* annotations of that type by "looking through" a container annotation.
*
* The annotations returned by this method could contain an element
@@ -147,6 +183,8 @@
* @see IncompleteAnnotationException
* @see MirroredTypeException
* @see MirroredTypesException
+ * @jls 9.6 Annotation Types
+ * @jls 9.6.1 Annotation Type Elements
*/
A[] getAnnotationsByType(Class annotationType);
}
diff -r 9f09744e221a -r c0b12eae2488 langtools/src/share/classes/javax/lang/model/type/ExecutableType.java
--- a/langtools/src/share/classes/javax/lang/model/type/ExecutableType.java Tue Mar 19 19:16:59 2013 -0700
+++ b/langtools/src/share/classes/javax/lang/model/type/ExecutableType.java Wed Mar 20 17:41:40 2013 -0700
@@ -30,7 +30,6 @@
import javax.lang.model.element.ExecutableElement;
-
/**
* Represents the type of an executable. An executable
* is a method, constructor, or initializer.