stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Reviewed-by: darcy
This commit is contained in:
Julia Boes 2020-12-16 10:46:39 +00:00
parent b5a3a5b621
commit 72dfba8053
9 changed files with 86 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
src/java.base/share/classes/java/lang/annotation/Annotation.java
View File

@ -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();

20
src/java.base/share/classes/java/lang/annotation/Documented.java
View File

@ -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 @@ package java.lang.annotation;
/**
* 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

30
src/java.base/share/classes/java/lang/annotation/ElementType.java
View File

@ -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 @@ package java.lang.annotation;
* #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 @@ package java.lang.annotation;
* @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 */

14
src/java.base/share/classes/java/lang/annotation/IncompleteAnnotationException.java
View File

@ -27,8 +27,8 @@ package java.lang.annotation;
/**
* 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 class IncompleteAnnotationException extends RuntimeException {
}
/**
* 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() {

20
src/java.base/share/classes/java/lang/annotation/Inherited.java
View File

@ -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.

14
src/java.base/share/classes/java/lang/annotation/Repeatable.java
View File

@ -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 @@ package java.lang.annotation;
@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();
}

12
src/java.base/share/classes/java/lang/annotation/Retention.java
View File

@ -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

8
src/java.base/share/classes/java/lang/annotation/RetentionPolicy.java
View File

@ -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

31
src/java.base/share/classes/java/lang/annotation/Target.java
View File

@ -26,22 +26,22 @@
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 {
@ -49,12 +49,13 @@ package java.lang.annotation;
* }
* </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 @@ package java.lang.annotation;
@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();