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

@@ -37,25 +37,34 @@
  * 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.
  *
+ * As defined by <cite>The Java&trade; Language Specification</cite>
+ * section {@jls 9.7.4}, an annotation on an element is a
+ * <em>declaration annotation</em> and an annotation on a type is a
+ * <em>type annotation</em>.
+ *
  * 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 the methods defined herein.
+ * throughout this interface to describe precisely which annotations,
+ * either declarations annotations or type annotations,
+ * are returned by the methods in this interface.
  *
  * <p>In the definitions below, an annotation <i>A</i> has an
  * annotation type <i>AT</i>. If <i>AT</i> is a repeatable annotation
  * type, the type of the containing annotation is <i>ATC</i>.
  *
  * <p>Annotation <i>A</i> is <em>directly present</em> on a construct
  * <i>C</i> if either:
  *
  * <ul>
  *
- * <li><i>A</i> is explicitly or implicitly declared as applying to
+ * <li><i>A</i> is {@linkplain
+ * javax.lang.model.util.Elements#getOrigin(AnnotatedConstruct,
+ * AnnotationMirror) explicitly or implicitly}
+ * declared as applying to
  * the source code representation of <i>C</i>.
  *
  * <p>Typically, if exactly one annotation of type <i>AT</i> appears in
  * the source code of representation of <i>C</i>, then <i>A</i> is
  * explicitly declared as applying to <i>C</i>.

@@ -120,10 +129,12 @@
  * </ul>
  *
  * @since 1.8
  * @jls 9.6 Annotation Types
  * @jls 9.6.4.3 {@code @Inherited}
+ * @jls 9.7.4 Where Annotations May Appear
+ * @jls 9.7.5 Multiple Annotations of the Same Type
  */
 public interface AnnotatedConstruct {
     /**
      * Returns the annotations that are <em>directly present</em> on
      * this construct.