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

rev 8793 : 8027413: Clarify javadoc for j.l.a.Target and j.l.a.ElementType
Reviewed-by: duke

*** 24,69 ****
   */
  
  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.
!  *
!  * 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:
   * <pre>
   *    @Target(ElementType.ANNOTATION_TYPE)
   *    public @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:
   * <pre>
   *    @Target({})
   *    public @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:
   * <pre>
   *    @Target({ElementType.FIELD, ElementType.METHOD, ElementType.FIELD})
   *    public @interface Bogus {
   *        ...
   *    }
   * </pre>
   *
   * @since 1.5
!  * @jls 9.6.3.1 @Target
   */
  @Documented
  @Retention(RetentionPolicy.RUNTIME)
  @Target(ElementType.ANNOTATION_TYPE)
  public @interface Target {
--- 24,79 ----
   */
  
  package java.lang.annotation;
  
  /**
!  * 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}.
!  *
!  * <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>
   *    @Target(ElementType.ANNOTATION_TYPE)
   *    public @interface MetaAnnotationType {
   *        ...
   *    }
   * </pre>
!  *
!  * <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>
   *    @Target({})
   *    public @interface MemberType {
   *        ...
   *    }
   * </pre>
!  *
!  * <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>
   *    @Target({ElementType.FIELD, ElementType.METHOD, ElementType.FIELD})
   *    public @interface Bogus {
   *        ...
   *    }
   * </pre>
   *
   * @since 1.5
!  * @jls 9.6.4.1 @Target
!  * @jls 9.7.4 Where Annotations May Appear
   */
  @Documented
  @Retention(RetentionPolicy.RUNTIME)
  @Target(ElementType.ANNOTATION_TYPE)
  public @interface Target {