8027413: Clarify javadoc for j.l.a.Target and j.l.a.ElementType

Reviewed-by: darcy

src/share/classes/java/lang/annotation/ElementType.java

 /*
- * Copyright (c) 2003, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 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
@@ -26,15 +26,49 @@
 package java.lang.annotation;
 
 /**
- * A program element type.  The constants of this enumerated type
- * provide a simple classification of the declared elements in a
- * Java program.
+ * The constants of this enumerated type provide a simple classification of the
+ * syntactic locations where annotations may appear in a Java program. These
+ * constants are used in {@link Target java.lang.annotation.Target}
+ * meta-annotations to specify where it is legal to write annotations of a
+ * given type.
  *
- * <p>These constants are used with the {@link Target} meta-annotation type
- * to specify where it is legal to use an annotation type.
+ * <p>The syntactic locations where annotations may appear are split into
+ * <em>declaration contexts</em> , where annotations apply to declarations, and
+ * <em>type contexts</em> , where annotations apply to types used in
+ * declarations and expressions.
+ *
+ * <p>The constants {@link #ANNOTATION_TYPE} , {@link #CONSTRUCTOR} , {@link
+ * #FIELD} , {@link #LOCAL_VARIABLE} , {@link #METHOD} , {@link #PACKAGE} ,
+ * {@link #PARAMETER} , {@link #TYPE} , and {@link #TYPE_PARAMETER} correspond
+ * to the declaration contexts in JLS 9.6.4.1.
+ *
+ * <p>For example, an annotation whose type is meta-annotated with
+ * {@code @Target(ElementType.FIELD)} may only be written as a modifier for a
+ * field declaration.
+ *
+ * <p>The constant {@link #TYPE_USE} corresponds to the 15 type contexts in JLS
+ * 4.11, as well as to two declaration contexts: type declarations (including
+ * annotation type declarations) and type parameter declarations.
+ *
+ * <p>For example, an annotation whose type is meta-annotated with
+ * {@code @Target(ElementType.TYPE_USE)} may be written on the type of a field
+ * (or within the type of the field, if it is a nested, parameterized, or array
+ * type), and may also appear as a modifier for, say, a class declaration.
+ *
+ * <p>The {@code TYPE_USE} constant includes type declarations and type
+ * parameter declarations as a convenience for designers of type checkers which
+ * give semantics to annotation types. For example, if the annotation type
+ * {@code NonNull} is meta-annotated with
+ * {@code @Target(ElementType.TYPE_USE)}, then {@code @NonNull}
+ * {@code class C {...}} could be treated by a type checker as indicating that
+ * all variables of class {@code C} are non-null, while still allowing
+ * variables of other classes to be non-null or not non-null based on whether
+ * {@code @NonNull} appears at the variable's declaration.
  *
  * @author  Joshua Bloch
  * @since 1.5
+ * @jls 9.6.4.1 @Target
+ * @jls 4.1 The Kinds of Types and Values
  */
 public enum ElementType {
     /** Class, interface (including annotation type), or enum declaration */

src/share/classes/java/lang/annotation/Target.java

@@ -26,33 +26,42 @@
 package java.lang.annotation;
 
 /**
- * Indicates the kinds of program element to which an annotation type
- * is applicable.  If a Target meta-annotation is not present on an
- * annotation type declaration, the declared type may be used on any
- * program element.  If such a meta-annotation is present, the compiler
- * will enforce the specified usage restriction.
+ * Indicates the contexts in which an annotation type is applicable. The
+ * declaration contexts and type contexts in which an annotation type may be
+ * applicable are specified in JLS 9.6.4.1, and denoted in source code by enum
+ * constants of {@link ElementType java.lang.annotation.ElementType}.
  *
- * For example, this meta-annotation indicates that the declared type is
- * itself a meta-annotation type.  It can only be used on annotation type
- * declarations:
+ * <p>If an {@code @Target} meta-annotation is not present on an annotation type
+ * {@code T} , then an annotation of type {@code T} may be written as a
+ * modifier for any declaration except a type parameter declaration.
+ *
+ * <p>If an {@code @Target} meta-annotation is present, the compiler will enforce
+ * the usage restrictions indicated by {@code ElementType}
+ * enum constants, in line with JLS 9.7.4.
+ *
+ * <p>For example, this {@code @Target} meta-annotation indicates that the
+ * declared type is itself a meta-annotation type.  It can only be used on
+ * annotation type declarations:
  * <pre>
  *    &#064;Target(ElementType.ANNOTATION_TYPE)
  *    public &#064;interface MetaAnnotationType {
  *        ...
  *    }
  * </pre>
- * This meta-annotation indicates that the declared type is intended solely
- * for use as a member type in complex annotation type declarations.  It
- * cannot be used to annotate anything directly:
+ *
+ * <p>This {@code @Target} meta-annotation indicates that the declared type is
+ * intended solely for use as a member type in complex annotation type
+ * declarations.  It cannot be used to annotate anything directly:
  * <pre>
  *    &#064;Target({})
  *    public &#064;interface MemberType {
  *        ...
  *    }
  * </pre>
- * It is a compile-time error for a single ElementType constant to
- * appear more than once in a Target annotation.  For example, the
- * following meta-annotation is illegal:
+ *
+ * <p>It is a compile-time error for a single {@code ElementType} constant to
+ * appear more than once in an {@code @Target} annotation.  For example, the
+ * following {@code @Target} meta-annotation is illegal:
  * <pre>
  *    &#064;Target({ElementType.FIELD, ElementType.METHOD, ElementType.FIELD})
  *    public &#064;interface Bogus {
@@ -61,7 +70,8 @@ package java.lang.annotation;
  * </pre>
  *
  * @since 1.5
- * @jls 9.6.3.1 @Target
+ * @jls 9.6.4.1 @Target
+ * @jls 9.7.4 Where Annotations May Appear
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)