8257637: Update usage of "type" terminology in java.lang.annotation

Reviewed-by: darcy

Author: Julia Boes

src/java.base/share/classes/java/lang/annotation/Annotation.java

@@ -26,16 +26,16 @@
 package java.lang.annotation;
 
 /**
- * The common interface extended by all annotation types.  Note that an
+ * The common interface extended by all annotation interfaces.  Note that an
  * interface that manually extends this one does <i>not</i> define
- * an annotation type.  Also note that this interface does not itself
- * define an annotation type.
+ * an annotation interface.  Also note that this interface does not itself
+ * define an annotation interface.
  *
- * More information about annotation types can be found in section {@jls 9.6} of
- * <cite>The Java Language Specification</cite>.
+ * More information about annotation interfaces can be found in section
+ * {@jls 9.6} of <cite>The Java Language Specification</cite>.
  *
  * The {@link java.lang.reflect.AnnotatedElement} interface discusses
- * compatibility concerns when evolving an annotation type from being
+ * compatibility concerns when evolving an annotation interface from being
  * non-repeatable to being repeatable.
  *
  * @author  Josh Bloch
@@ -46,7 +46,7 @@ public interface Annotation {
      * Returns true if the specified object represents an annotation
      * that is logically equivalent to this one.  In other words,
      * returns true if the specified object is an instance of the same
-     * annotation type as this instance, all of whose members are equal
+     * annotation interface as this instance, all of whose members are equal
      * to the corresponding member of this annotation, as defined below:
      * <ul>
      *    <li>Two corresponding primitive typed members whose values are
@@ -127,15 +127,15 @@ public interface Annotation {
     String toString();
 
     /**
-     * Returns the annotation type of this annotation.
+     * Returns the annotation interface of this annotation.
      *
      * @apiNote Implementation-dependent classes are used to provide
      * the implementations of annotations. Therefore, calling {@link
      * Object#getClass getClass} on an annotation will return an
      * implementation-dependent class. In contrast, this method will
-     * reliably return the annotation type of the annotation.
+     * reliably return the annotation interface of the annotation.
      *
-     * @return the annotation type of this annotation
+     * @return the annotation interface of this annotation
      * @see Enum#getDeclaringClass
      */
     Class<? extends Annotation> annotationType();

src/java.base/share/classes/java/lang/annotation/Documented.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2020, 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
@@ -27,23 +27,23 @@
 
 /**
  * If the annotation {@code @Documented} is present on the declaration
- * of an annotation type <i>A</i>, then any {@code @A} annotation on
+ * of an annotation interface <i>A</i>, then any {@code @A} annotation on
  * an element is considered part of the element's public contract.
  *
- * In more detail, when an annotation type <i>A</i> is annotated with
- * {@code Documented}, the presence and value of annotations of type
- * <i>A</i> are a part of the public contract of the elements <i>A</i>
+ * In more detail, when an annotation interface <i>A</i> is annotated with
+ * {@code Documented}, the presence and value of <i>A</i> annotations
+ * are a part of the public contract of the elements <i>A</i>
  * annotates.
  *
- * Conversely, if an annotation type <i>B</i> is <em>not</em>
+ * Conversely, if an annotation interface <i>B</i> is <em>not</em>
  * annotated with {@code Documented}, the presence and value of
  * <i>B</i> annotations are <em>not</em> part of the public contract
  * of the elements <i>B</i> annotates.
  *
- * Concretely, if an annotation type is annotated with {@code
- * Documented}, by default a tool like javadoc will display
- * annotations of that type in its output while annotations of
- * annotation types without {@code Documented} will not be displayed.
+ * Concretely, if an annotation interface is annotated with {@code Documented},
+ * by default a tool like javadoc will display annotations of that interface
+ * in its output while annotations of annotation interfaces without
+ * {@code Documented} will not be displayed.
  *
  * @author  Joshua Bloch
  * @since 1.5

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

@@ -26,7 +26,7 @@
 package java.lang.annotation;
 
 /**
- * The constants of this enumerated type provide a simple classification of the
+ * The constants of this enumerated class provide a simple classification of the
  * syntactic locations where annotations may appear in a Java program. These
  * constants are used in {@link java.lang.annotation.Target Target}
  * meta-annotations to specify where it is legal to write annotations of a
@@ -42,23 +42,25 @@
  * #MODULE}, {@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
+ * <p>For example, an annotation whose interface 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 type contexts in JLS
- * 4.11, as well as to two declaration contexts: type declarations (including
- * annotation type declarations) and type parameter declarations.
+ * 4.11, as well as to two declaration contexts: class and interface
+ * declarations (including annotation 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>For example, an annotation whose interface is meta-annotated with
+ * {@code @Target(ElementType.TYPE_USE)} may be written on the class or
+ * interface of a field (or within the class or interface of the field, if it
+ * is a nested or parameterized class or interface, or array class), 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
+ * <p>The {@code TYPE_USE} constant includes class and interface declarations
+ * and type parameter declarations as a convenience for designers of
+ * type checkers which give semantics to annotation interfaces. For example,
+ * if the annotation interface {@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
@@ -71,7 +73,7 @@
  * @jls 4.1 The Kinds of Types and Values
  */
 public enum ElementType {
-    /** Class, interface (including annotation type), enum, or record
+    /** Class, interface (including annotation interface), enum, or record
      * declaration */
     TYPE,
 
@@ -90,7 +92,7 @@ public enum ElementType {
     /** Local variable declaration */
     LOCAL_VARIABLE,
 
-    /** Annotation type declaration */
+    /** Annotation interface declaration (Formerly known as an annotation type.) */
     ANNOTATION_TYPE,
 
     /** Package declaration */

src/java.base/share/classes/java/lang/annotation/IncompleteAnnotationException.java

@@ -27,8 +27,8 @@
 
 /**
  * Thrown to indicate that a program has attempted to access an element of
- * an annotation type that was added to the annotation type definition after
- * the annotation was compiled (or serialized).  This exception will not be
+ * an annotation interface that was added to the annotation interface definition
+ * after the annotation was compiled (or serialized). This exception will not be
  * thrown if the new element has a default value.
  * This exception can be thrown by the {@linkplain
  * java.lang.reflect.AnnotatedElement API used to read annotations
@@ -43,7 +43,7 @@ public class IncompleteAnnotationException extends RuntimeException {
     private static final long serialVersionUID = 8445097402741811912L;
 
     /**
-     * The annotation type.
+     * The annotation interface.
      */
     private Class<? extends Annotation> annotationType;
     /**
@@ -53,9 +53,9 @@ public class IncompleteAnnotationException extends RuntimeException {
 
     /**
      * Constructs an IncompleteAnnotationException to indicate that
-     * the named element was missing from the specified annotation type.
+     * the named element was missing from the specified annotation interface.
      *
-     * @param annotationType the Class object for the annotation type
+     * @param annotationType the Class object for the annotation interface
      * @param elementName the name of the missing element
      * @throws NullPointerException if either parameter is {@code null}
      */
@@ -70,10 +70,10 @@ public IncompleteAnnotationException(
     }
 
     /**
-     * Returns the Class object for the annotation type with the
+     * Returns the Class object for the annotation interface with the
      * missing element.
      *
-     * @return the Class object for the annotation type with the
+     * @return the Class object for the annotation interface with the
      *     missing element
      */
     public Class<? extends Annotation> annotationType() {

src/java.base/share/classes/java/lang/annotation/Inherited.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2020, 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,18 +26,18 @@
 package java.lang.annotation;
 
 /**
- * Indicates that an annotation type is automatically inherited.  If
- * an Inherited meta-annotation is present on an annotation type
- * declaration, and the user queries the annotation type on a class
- * declaration, and the class declaration has no annotation for this type,
+ * Indicates that an annotation interface is automatically inherited.  If
+ * an Inherited meta-annotation is present on an annotation interface
+ * declaration, and the user queries the annotation interface on a class
+ * declaration, and the class declaration has no annotation for this interface,
  * then the class's superclass will automatically be queried for the
- * annotation type.  This process will be repeated until an annotation for this
- * type is found, or the top of the class hierarchy (Object)
- * is reached.  If no superclass has an annotation for this type, then
+ * annotation interface.  This process will be repeated until an annotation for
+ * this interface is found, or the top of the class hierarchy (Object)
+ * is reached.  If no superclass has an annotation for this interface, then
  * the query will indicate that the class in question has no such annotation.
  *
- * <p>Note that this meta-annotation type has no effect if the annotated
- * type is used to annotate anything other than a class.  Note also
+ * <p>Note that this meta-annotation interface has no effect if the annotated
+ * interface is used to annotate anything other than a class.  Note also
  * that this meta-annotation only causes annotations to be inherited
  * from superclasses; annotations on implemented interfaces have no
  * effect.

src/java.base/share/classes/java/lang/annotation/Repeatable.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2020, 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,11 +26,11 @@
 package java.lang.annotation;
 
 /**
- * The annotation type {@code java.lang.annotation.Repeatable} is
- * used to indicate that the annotation type whose declaration it
+ * The annotation interface {@code java.lang.annotation.Repeatable} is
+ * used to indicate that the annotation interface whose declaration it
  * (meta-)annotates is <em>repeatable</em>. The value of
  * {@code @Repeatable} indicates the <em>containing annotation
- * type</em> for the repeatable annotation type.
+ * interface</em> for the repeatable annotation interface.
  *
  * @since 1.8
  * @jls 9.6.3 Repeatable Annotation Interfaces
@@ -41,9 +41,9 @@
 @Target(ElementType.ANNOTATION_TYPE)
 public @interface Repeatable {
     /**
-     * Indicates the <em>containing annotation type</em> for the
-     * repeatable annotation type.
-     * @return the containing annotation type
+     * Indicates the <em>containing annotation interface</em> for the
+     * repeatable annotation interface.
+     * @return the containing annotation interface
      */
     Class<? extends Annotation> value();
 }

src/java.base/share/classes/java/lang/annotation/Retention.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2020, 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,15 @@
 package java.lang.annotation;
 
 /**
- * Indicates how long annotations with the annotated type are to
+ * Indicates how long annotations with the annotated interface are to
  * be retained.  If no Retention annotation is present on
- * an annotation type declaration, the retention policy defaults to
+ * an annotation interface declaration, the retention policy defaults to
  * {@code RetentionPolicy.CLASS}.
  *
  * <p>A Retention meta-annotation has effect only if the
- * meta-annotated type is used directly for annotation.  It has no
- * effect if the meta-annotated type is used as a member type in
- * another annotation type.
+ * meta-annotated interface is used directly for annotation.  It has no
+ * effect if the meta-annotated interface is used as a member interface in
+ * another annotation interface.
  *
  * @author  Joshua Bloch
  * @since 1.5

src/java.base/share/classes/java/lang/annotation/RetentionPolicy.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2020, 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,10 +26,10 @@
 package java.lang.annotation;
 
 /**
- * Annotation retention policy.  The constants of this enumerated type
+ * Annotation retention policy.  The constants of this enumerated class
  * describe the various policies for retaining annotations.  They are used
- * in conjunction with the {@link Retention} meta-annotation type to specify
- * how long annotations are to be retained.
+ * in conjunction with the {@link Retention} meta-annotation interface to
+ * specify how long annotations are to be retained.
  *
  * @author  Joshua Bloch
  * @since 1.5

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

@@ -26,35 +26,36 @@
 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}.
+ * Indicates the contexts in which an annotation interface is applicable. The
+ * declaration contexts and type contexts in which an annotation interface 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 not present on an annotation
+ * interface {@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:
+ * declared interface is itself a meta-annotation interface.  It can only be
+ * used on annotation interface declarations:
  * <pre>
  *    &#064;Target(ElementType.ANNOTATION_TYPE)
  *    public &#064;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:
+ * <p>This {@code @Target} meta-annotation indicates that the declared class or
+ * interface is intended solely for use as a member class or interface in
+ * complex annotation interface declarations.  It cannot be used to annotate
+ * anything directly:
  * <pre>
  *    &#064;Target({})
- *    public &#064;interface MemberType {
+ *    public &#064;interface MemberInterface {
  *        ...
  *    }
  * </pre>
@@ -79,9 +80,9 @@
 @Target(ElementType.ANNOTATION_TYPE)
 public @interface Target {
     /**
-     * Returns an array of the kinds of elements an annotation type
+     * Returns an array of the kinds of elements an annotation interface
      * can be applied to.
-     * @return an array of the kinds of elements an annotation type
+     * @return an array of the kinds of elements an annotation interface
      * can be applied to
      */
     ElementType[] value();