src/share/classes/javax/lang/model/AnnotatedConstruct.java

@@ -37,40 +37,67 @@
  * javax.lang.model.element.Element element} or a {@linkplain
  * javax.lang.model.type.TypeMirror type}.  Annotations on an element
  * are on a <em>declaration</em>, whereas annotations on a type are on
  * a specific <em>use</em> of a type name.
  *
- * The terms <em>directly present</em> and <em>present</em> are used
+ * The terms <em>directly present</em>, <em>present</em>,
+ * <em>indirectly present</em>, and <em>associated </em> are used
  * throughout this interface to describe precisely which annotations
- * are returned by methods:
+ * are returned by its methods.
  *
  * <p>An annotation <i>A</i> is <em>directly present</em> on a
- * construct <i>E</i> if <i>E</i> is annotated, and:
+ * construct <i>E</i> if either:
+ * <ul>
+ *
+ * <li><i>A</i> appears exactly once in the source code representation
+ * for <i>E</i>.
+ *
+ * <li><i>A</i> is the container annotation for a repeatable
+ * annotation type <i>R</i> and the source code for <i>E</i> has
+ * multiple annotations of type <i>R</i>.
+ *
+ * <li> A representation of <i>A</i> appears in the executable output
+ * for <i>E</i>, such as the {@code RuntimeVisibleAnnotations} or
+ * {@code RuntimeVisibleParameterAnnotations} attributes of a class
+ * file.
+ *
+ * </ul>
+ *
+ * <p>An annotation <i>A</i> is <em>present</em> on a
+ * construct <i>E</i> if either:
+ * <ul>
+ *
+ * <li><i>A</i> is directly present on <i>E</i>.
+ *
+ * <li>No annotation of <i>A</i>'s type is directly present on
+ * <i>E</i>, and <i>E</i> is a class and <i>A</i>'s type is inheritable
+ * and <i>A</i> is present on the superclass of <i>E</i>.
+ *
+ * </ul>
+ *
+ * An annotation <i>A</i> is <em>indirectly present</em> on an element
+ * <i>E</i> if:
  *
  * <ul>
  *
- * <li> for an invocation of {@code getAnnotation(Class<T>)} or
- * {@code getAnnotationMirrors()}, <i>E</i>'s annotations contain <i>A</i>.
+ * <li> <i>A</i>'s type is repeatable with a containing annotation type <i>C</i>
  *
- * <li> for an invocation of getAnnotationsByType(Class<T>),
- * <i>E</i>'s annotations either contain <i>A</i> or, if the type of
- * <i>A</i> is repeatable, contain exactly one annotation whose value
- * element contains <i>A</i> and whose type is the containing
- * annotation type of <i>A</i>'s type.
+ * <li> An annotation of type <i>C</i> is directly present on <i>E</i>.
  *
  * </ul>
  *
- * <p>An annotation A is <em>present</em> on a construct E if either:
+ * An annotation <i>A</i> is <em>associated</em> with an element
+ * <i>E</i> if either:
  *
  * <ul>
- *  <li> <i>A</i> is <em>directly present</em> on <i>E</i>; or
  *
- *  <li> <i>A</i> is not <em>directly present</em> on <i>E</i>, and
- *  <i>E</i> is an element representing a class, and <i>A</i>'s type
- *  is inheritable, and <i>A</i> is <em>present</em> on the element
- *  representing the superclass of <i>E</i>.
+ * <li> <i>A</i> is directly or indirectly present on <i>E</i>.
  *
+ * <li> No annotation of <i>A</i>'s type is directly or indirectly
+ * present on <i>E</i>, <i>E</i> is a class, and <i>A</i>'s type is
+ * inheritable, and <i>A</i> is associated with the superclass of
+ * <i>E</i>.
  * </ul>
  *
  * @since 1.8
  * @jls 9.6 Annotation Types
  * @jls 9.6.3.3 @Inherited

@@ -132,14 +159,14 @@
      * @jls 9.6.1 Annotation Type Elements
      */
     <A extends Annotation> A getAnnotation(Class<A> annotationType);
 
     /**
-     * Returns annotations that are <em>present</em> on this construct.
+     * Returns annotations that are <em>associated</em> with this construct.
      *
-     * If there are no annotations <em>present</em> on this construct,
-     * the return value is an array of length 0.
+     * If there are no annotations associated with 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 <em>repeatable
      * annotation type</em>, and if so, attempts to find one or more
      * annotations of that type by "looking through" a container annotation.