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

8257638: Update usage of "type" terminology in javax.lang.model

Browse Source 
Reviewed-by: jjg
This commit is contained in:
Joe Darcy 2020-12-10 02:59:26 +00:00
parent f631a9901f
commit d2f9e31ae4
17 changed files with 176 additions and 164 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
src/java.compiler/share/classes/javax/annotation/processing/AbstractProcessor.java
View File

@ -39,9 +39,9 @@ import javax.tools.Diagnostic;
* superclass for most concrete annotation processors. This class
* examines annotation values to compute the {@linkplain
* #getSupportedOptions options}, {@linkplain
* #getSupportedAnnotationTypes annotation types}, and {@linkplain
* #getSupportedSourceVersion source version} supported by its
* subtypes.
* #getSupportedAnnotationTypes annotation interfaces}, and
* {@linkplain #getSupportedSourceVersion source version} supported by
* its subtypes.
*
* <p>The getter methods may {@linkplain Messager#printMessage issue
* warnings} about noteworthy conditions using the facilities available
@ -98,8 +98,8 @@ public abstract class AbstractProcessor implements Processor {
* then any leading {@linkplain Processor#getSupportedAnnotationTypes
* module prefixes} are stripped from the names.
*
* @return the names of the annotation types supported by this
* processor, or an empty set if none
* @return the names of the annotation interfaces supported by
* this processor, or an empty set if none
*/
public Set<String> getSupportedAnnotationTypes() {
SupportedAnnotationTypes sat = this.getClass().getAnnotation(SupportedAnnotationTypes.class);

57
src/java.compiler/share/classes/javax/annotation/processing/Filer.java
View File

@ -66,9 +66,9 @@ import java.io.IOException;
* <p>The file creation methods take a variable number of arguments to
* allow the <em>originating elements</em> to be provided as hints to
* the tool infrastructure to better manage dependencies. The
* originating elements are the types or packages (representing {@code
* package-info} files) or modules (representing {@code
* module-info} files) which caused an annotation processor to
* originating elements are the classes or interfaces or packages
* (representing {@code package-info} files) or modules (representing
* {@code module-info} files) which caused an annotation processor to
* attempt to create a new file. For example, if an annotation
* processor tries to create a source file, {@code
* GeneratedFromUserSource}, in response to processing
@ -107,14 +107,15 @@ import java.io.IOException;
* <p> In general, processors must not knowingly attempt to overwrite
* existing files that were not generated by some processor. A {@code
* Filer} may reject attempts to open a file corresponding to an
* existing type, like {@code java.lang.Object}. Likewise, the
* existing class or interface, like {@code java.lang.Object}. Likewise, the
* invoker of the annotation processing tool must not knowingly
* configure the tool such that the discovered processors will attempt
* to overwrite existing files that were not generated.
*
* <p> Processors can indicate a source or class file is generated by
* including a {@link javax.annotation.processing.Generated} annotation if the
* environment is configured so that that type is accessible.
* including a {@link javax.annotation.processing.Generated}
* annotation if the environment is configured so that that class or
* interface is accessible.
*
* @apiNote Some of the effect of overwriting a file can be
* achieved by using a <i>decorator</i>-style pattern. Instead of
@ -133,8 +134,8 @@ import java.io.IOException;
public interface Filer {
/**
* Creates a new source file and returns an object to allow
* writing to it. A source file for a type, or a package can
* be created.
* writing to it. A source file for a class, interface, or a
* package can be created.
*
* The file's name and path (relative to the {@linkplain
* StandardLocation#SOURCE_OUTPUT root output location for source
@ -142,9 +143,9 @@ public interface Filer {
* that file as well as the specified module for the item (if
* any).
*
* If more than one type is being declared in a single file (that
* If more than one class or interface is being declared in a single file (that
* is, a single compilation unit), the name of the file should
* correspond to the name of the principal top-level type (the
* correspond to the name of the principal top-level class or interface (the
* public one, for example).
*
* <p>A source file can also be created to hold information about
@ -155,7 +156,7 @@ public interface Filer {
*
* <p>The optional module name is prefixed to the type name or
* package name and separated using a "{@code /}" character. For
* example, to create a source file for type {@code a.B} in module
* example, to create a source file for class {@code a.B} in module
* {@code foo}, use a {@code name} argument of {@code "foo/a.B"}.
*
* <p>If no explicit module prefix is given and modules are supported
@ -194,15 +195,15 @@ public interface Filer {
* as the target module. A separate option may be used to provide the target
* module if it cannot be determined using the above rules.
*
* @param name canonical (fully qualified) name of the principal type
* @param name canonical (fully qualified) name of the principal class or interface
* being declared in this file or a package name followed by
* {@code ".package-info"} for a package information file
* @param originatingElements type or package or module elements causally
* associated with the creation of this file, may be elided or
* {@code null}
* @param originatingElements class, interface, package, or module
* elements causally associated with the creation of this file,
* may be elided or {@code null}
* @return a {@code JavaFileObject} to write the new source file
* @throws FilerException if the same pathname has already been
* created, the same type has already been created, the name is
* created, the same class or interface has already been created, the name is
* otherwise not valid for the entity requested to being created,
* if the target module cannot be determined, if the target
* module is not writable, or a module is specified when the environment
@ -215,7 +216,7 @@ public interface Filer {
/**
* Creates a new class file, and returns an object to allow
* writing to it. A class file for a type, or a package can
* writing to it. A class file for a class, interface, or a package can
* be created.
*
* The file's name and path (relative to the {@linkplain
@ -231,7 +232,7 @@ public interface Filer {
*
* <p>The optional module name is prefixed to the type name or
* package name and separated using a "{@code /}" character. For
* example, to create a class file for type {@code a.B} in module
* example, to create a class file for class {@code a.B} in module
* {@code foo}, use a {@code name} argument of {@code "foo/a.B"}.
*
* <p>If no explicit module prefix is given and modules are supported
@ -259,15 +260,16 @@ public interface Filer {
* as the target module. A separate option may be used to provide the target
* module if it cannot be determined using the above rules.
*
* @param name binary name of the type being written or a package name followed by
* {@code ".package-info"} for a package information file
* @param originatingElements type or package or module elements causally
* associated with the creation of this file, may be elided or
* {@code null}
* @param name binary name of the class or interface being written
* or a package name followed by {@code ".package-info"} for a
* package information file
* @param originatingElements class or interface or package or
* module elements causally associated with the creation of this
* file, may be elided or {@code null}
* @return a {@code JavaFileObject} to write the new class file
* @throws FilerException if the same pathname has already been
* created, the same type has already been created, the name is
* not valid for a type, if the target module cannot be determined,
* created, the same class or interface has already been created, the name is
* not valid for a class or interface, if the target module cannot be determined,
* if the target module is not writable, or a module is specified when
* the environment doesn't support modules.
* @throws IOException if the file cannot be created
@ -330,8 +332,9 @@ public interface Filer {
* @param moduleAndPkg module and/or package relative to which the file
* should be named, or the empty string if none
* @param relativeName final pathname components of the file
* @param originatingElements type or package or module elements causally
* associated with the creation of this file, may be elided or
* @param originatingElements class or interface or package or
* module elements causally associated with the creation of this
* file, may be elided or
* {@code null}
* @return a {@code FileObject} to write the new resource
* @throws IOException if the file cannot be created

7
src/java.compiler/share/classes/javax/annotation/processing/FilerException.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2017, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 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
@ -31,8 +31,9 @@ import java.io.IOException;
* Indicates a {@link Filer} detected an attempt to open a file that
* would violate the guarantees provided by the {@code Filer}. Those
* guarantees include not creating the same file more than once, not
* creating multiple files corresponding to the same type or package, and not
* creating files for types with invalid names.
* creating multiple files corresponding to the same class or
* interface or package, and not creating files for classes or
* interfaces with invalid names.
*
* @author Joseph D. Darcy
* @author Scott Seligman

88
src/java.compiler/share/classes/javax/annotation/processing/Processor.java
View File

@ -90,45 +90,45 @@ import javax.lang.model.SourceVersion;
* configuration mechanisms, such as command line options; for
* details, refer to the particular tool's documentation. Which
* processors the tool asks to {@linkplain #process run} is a function
* of the types of the annotations <em>{@linkplain AnnotatedConstruct present}</em>
* on the {@linkplain
* of the interfaces of the annotations <em>{@linkplain
* AnnotatedConstruct present}</em> on the {@linkplain
* RoundEnvironment#getRootElements root elements}, what {@linkplain
* #getSupportedAnnotationTypes annotation types a processor
* #getSupportedAnnotationTypes annotation interfaces a processor
* supports}, and whether or not a processor {@linkplain #process
* claims the annotation types it processes}. A processor will be asked to
* process a subset of the annotation types it supports, possibly an
* empty set.
* claims the annotation interfaces it processes}. A processor will
* be asked to process a subset of the annotation interfaces it
* supports, possibly an empty set.
*
* For a given round, the tool computes the set of annotation types
* that are present on the elements enclosed within the root elements.
* If there is at least one annotation type present, then as
* processors claim annotation types, they are removed from the set of
* unmatched annotation types. When the set is empty or no more
* processors are available, the round has run to completion. If
* there are no annotation types present, annotation processing still
* occurs but only <i>universal processors</i> which support
* processing all annotation types, {@code "*"}, can claim the (empty)
* set of annotation types.
* For a given round, the tool computes the set of annotation
* interfaces that are present on the elements enclosed within the
* root elements. If there is at least one annotation interface
* present, then as processors claim annotation interfaces, they are
* removed from the set of unmatched annotation interfaces. When the
* set is empty or no more processors are available, the round has run
* to completion. If there are no annotation interfaces present,
* annotation processing still occurs but only <i>universal
* processors</i> which support processing all annotation interfaces,
* {@code "*"}, can claim the (empty) set of annotation interfaces.
*
* <p>An annotation type is considered present if there is at least
* one annotation of that type present on an element enclosed within
* <p>An annotation interface is considered present if there is at least
* one annotation of that interface present on an element enclosed within
* the root elements of a round. For this purpose, a type parameter is
* considered to be enclosed by its {@linkplain
* TypeParameterElement#getGenericElement generic
* element}.
* For this purpose, a package element is <em>not</em> considered to
* enclose the top-level types within that package. (A root element
* representing a package is created when a {@code package-info} file
* is processed.) Likewise, for this purpose, a module element is
* <em>not</em> considered to enclose the packages within that
* module. (A root element representing a module is created when a
* {@code module-info} file is processed.)
* enclose the top-level classes and interfaces within that
* package. (A root element representing a package is created when a
* {@code package-info} file is processed.) Likewise, for this
* purpose, a module element is <em>not</em> considered to enclose the
* packages within that module. (A root element representing a module
* is created when a {@code module-info} file is processed.)
*
* Annotations on {@linkplain
* java.lang.annotation.ElementType#TYPE_USE type uses}, as opposed to
* annotations on elements, are ignored when computing whether or not
* an annotation type is present.
* an annotation interface is present.
*
* <p>An annotation is <em>present</em> if it meets the definition of being
* present given in {@link AnnotatedConstruct}. In brief, an
@ -141,10 +141,10 @@ import javax.lang.model.SourceVersion;
* Elements#getAllAnnotationMirrors(Element)} called on that element. Since
* annotations inside container annotations are not considered
* present, to properly process {@linkplain
* java.lang.annotation.Repeatable repeatable annotation types},
* java.lang.annotation.Repeatable repeatable annotation interfaces},
* processors are advised to include both the repeatable annotation
* type and its containing annotation type in the set of {@linkplain
* #getSupportedAnnotationTypes() supported annotation types} of a
* interface and its containing annotation interface in the set of {@linkplain
* #getSupportedAnnotationTypes() supported annotation interfaces} of a
* processor.
*
* <p>Note that if a processor supports {@code "*"} and returns {@code
@ -240,17 +240,17 @@ public interface Processor {
Set<String> getSupportedOptions();
/**
* Returns the names of the annotation types supported by this
* Returns the names of the annotation interfaces supported by this
* processor. An element of the result may be the canonical
* (fully qualified) name of a supported annotation type.
* (fully qualified) name of a supported annotation interface.
* Alternately it may be of the form &quot;<code><i>name</i>.*</code>&quot;
* representing the set of all annotation types with canonical
* representing the set of all annotation interfaces with canonical
* names beginning with &quot;<code><i>name.</i></code>&quot;.
*
* In either of those cases, the name of the annotation type can
* In either of those cases, the name of the annotation interface can
* be optionally preceded by a module name followed by a {@code
* "/"} character. For example, if a processor supports {@code
* "a.B"}, this can include multiple annotation types named {@code
* "a.B"}, this can include multiple annotation interfaces named {@code
* a.B} which reside in different modules. To only support {@code
* a.B} in the {@code foo} module, instead use {@code "foo/a.B"}.
*
@ -259,11 +259,11 @@ public interface Processor {
* environment where modules are not supported, such as an
* annotation processing environment configured for a {@linkplain
* javax.annotation.processing.ProcessingEnvironment#getSourceVersion
* source version} without modules, then the annotation types with
* source version} without modules, then the annotation interfaces with
* a module name do <em>not</em> match.
*
* Finally, {@code "*"} by itself represents the set of all
* annotation types, including the empty set. Note that a
* annotation interfaces, including the empty set. Note that a
* processor should not claim {@code "*"} unless it is actually
* processing all files; claiming unnecessary annotations may
* cause a performance slowdown in some environments.
@ -291,13 +291,13 @@ public interface Processor {
*
* @apiNote When running in an environment which supports modules,
* processors are encouraged to include the module prefix when
* describing their supported annotation types. The method {@link
* describing their supported annotation interfaces. The method {@link
* AbstractProcessor#getSupportedAnnotationTypes
* AbstractProcessor.getSupportedAnnotationTypes} provides support
* for stripping off the module prefix when running in an
* environment without modules.
*
* @return the names of the annotation types supported by this processor
* @return the names of the annotation interfaces supported by this processor
* or an empty set if none
* @see javax.annotation.processing.SupportedAnnotationTypes
* @jls 3.8 Identifiers
@ -322,12 +322,12 @@ public interface Processor {
void init(ProcessingEnvironment processingEnv);
/**
* Processes a set of annotation types on type elements
* Processes a set of annotation interfaces on type elements
* originating from the prior round and returns whether or not
* these annotation types are claimed by this processor. If {@code
* true} is returned, the annotation types are claimed and subsequent
* these annotation interfaces are claimed by this processor. If {@code
* true} is returned, the annotation interfaces are claimed and subsequent
* processors will not be asked to process them; if {@code false}
* is returned, the annotation types are unclaimed and subsequent
* is returned, the annotation interfaces are unclaimed and subsequent
* processors may be asked to process them. A processor may
* always return the same boolean value or may vary the result
* based on its own chosen criteria.
@ -336,9 +336,9 @@ public interface Processor {
* "*"} and the root elements have no annotations. A {@code
* Processor} must gracefully handle an empty set of annotations.
*
* @param annotations the annotation types requested to be processed
* @param annotations the annotation interfaces requested to be processed
* @param roundEnv environment for information about the current and prior round
* @return whether or not the set of annotation types are claimed by this processor
* @return whether or not the set of annotation interfaces are claimed by this processor
*/
boolean process(Set<? extends TypeElement> annotations,
RoundEnvironment roundEnv);
@ -381,7 +381,7 @@ public interface Processor {
*
* (A Mersenne prime is prime number of the form
* 2<sup><i>n</i></sup> - 1.) Given an {@code AnnotationMirror}
* for this annotation type, a list of all such primes in the
* for this annotation interface, a list of all such primes in the
* {@code int} range could be returned without examining any other
* arguments to {@code getCompletions}:
*

6
src/java.compiler/share/classes/javax/annotation/processing/SupportedAnnotationTypes.java
View File

@ -30,8 +30,8 @@ import static java.lang.annotation.RetentionPolicy.*;
import static java.lang.annotation.ElementType.*;
/**
* An annotation used to indicate what annotation types an annotation
* processor supports. The {@link
* An annotation used to indicate what annotation interfaces an
* annotation processor supports. The {@link
* Processor#getSupportedAnnotationTypes} method can construct its
* result from the value of this annotation, as done by {@link
* AbstractProcessor#getSupportedAnnotationTypes}. Only {@linkplain
@ -48,7 +48,7 @@ import static java.lang.annotation.ElementType.*;
@Retention(RUNTIME)
public @interface SupportedAnnotationTypes {
/**
* {@return the names of the supported annotation types}
* {@return the names of the supported annotation interfaces}
*/
String [] value();
}

2
src/java.compiler/share/classes/javax/lang/model/element/AnnotationMirror.java
View File

@ -30,7 +30,7 @@ import javax.lang.model.type.DeclaredType;
/**
* Represents an annotation. An annotation associates a value with
* each element of an annotation type.
* each element of an annotation interface.
*
* <p> Annotations should be compared using the {@code equals}
* method. There is no guarantee that any particular annotation will

2
src/java.compiler/share/classes/javax/lang/model/element/AnnotationValue.java
View File

@ -26,7 +26,7 @@
package javax.lang.model.element;
/**
* Represents a value of an annotation type element.
* Represents a value of an annotation interface element.
* A value is of one of the following types:
* <ul><li> a wrapper class (such as {@link Integer}) for a primitive type
* <li> {@code String}

2
src/java.compiler/share/classes/javax/lang/model/element/AnnotationValueVisitor.java
View File

@ -31,7 +31,7 @@ import javax.lang.model.type.TypeMirror;
import javax.lang.model.util.*;
/**
* A visitor of the values of annotation type elements, using a
* A visitor of the values of annotation interface elements, using a
* variant of the visitor design pattern. Unlike a standard visitor
* which dispatches based on the concrete type of a member of a type
* hierarchy, this visitor dispatches based on the type of data

16
src/java.compiler/share/classes/javax/lang/model/element/Element.java
View File

@ -125,12 +125,12 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
Set<Modifier> getModifiers();
/**
* {@return the simple (unqualified) name of this element} The
* name of a generic type does not include any reference to its
* formal type parameters.
* {@return the simple (unqualified) name of this element} The
* name of a generic class or interface does not include any
* reference to its formal type parameters.
*
* For example, the simple name of the type element {@code
* java.util.Set<E>} is {@code "Set"}.
* For example, the simple name of the type element representing
* {@code java.util.Set<E>} is {@code "Set"}.
*
* If this element represents an unnamed {@linkplain
* PackageElement#getSimpleName package} or unnamed {@linkplain
@ -166,7 +166,7 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
* element is returned.
*
* <li> If this is a {@linkplain TypeElement#getEnclosingElement
* top-level type}, its package is returned.
* top-level class or interface}, its package is returned.
*
* <li> If this is a {@linkplain
* PackageElement#getEnclosingElement package}, its module is
@ -184,7 +184,7 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
*
* <li> If this is a {@linkplain
* RecordComponentElement#getEnclosingElement record component},
* {@linkplain TypeElement the type} which declares the
* {@linkplain TypeElement the record class} which declares the
* record component is returned.
*
* <li> If this is a {@linkplain ModuleElement#getEnclosingElement
@ -204,7 +204,7 @@ public interface Element extends javax.lang.model.AnnotatedConstruct {
*
* A {@linkplain TypeElement#getEnclosedElements class or
* interface} is considered to enclose the fields, methods,
* constructors, record components, and member types that it directly declares.
* constructors, record components, and member classes and interfaces that it directly declares.
*
* A {@linkplain PackageElement#getEnclosedElements package}
* encloses the top-level classes and interfaces within it, but is

8
src/java.compiler/share/classes/javax/lang/model/element/ElementKind.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 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
@ -44,7 +44,7 @@ public enum ElementKind {
PACKAGE,
// Declared types
/** An enum type. */
/** An enum class. */
ENUM,
/**
* A class not described by a more specific kind (like {@code
@ -52,7 +52,7 @@ public enum ElementKind {
*/
CLASS,
/** An annotation type. */
/** An annotation interface. (Formerly known as an annotation type.) */
ANNOTATION_TYPE,
/**
* An interface not described by a more specific kind (like
@ -109,7 +109,7 @@ public enum ElementKind {
MODULE,
/**
* A record type.
* A record class.
* @since 16
*/
RECORD,

6
src/java.compiler/share/classes/javax/lang/model/element/ExecutableElement.java
View File

@ -123,9 +123,9 @@ public interface ExecutableElement extends Element, Parameterizable {
/**
* Returns the default value if this executable is an annotation
* type element. Returns {@code null} if this method is not an
* annotation type element, or if it is an annotation type element
* with no default value.
* interface element. Returns {@code null} if this method is not
* an annotation interface element, or if it is an annotation
* interface element with no default value.
*
* @return the default value, or {@code null} if none
*/

13
src/java.compiler/share/classes/javax/lang/model/element/NestingKind.java
View File

@ -1,5 +1,5 @@
/*
* Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
* Copyright (c) 2005, 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
@ -83,24 +83,27 @@ package javax.lang.model.element;
*/
public enum NestingKind {
/**
* A top-level type, not contained within another type.
* A top-level class or interface, not contained within another
* class or interface.
*/
TOP_LEVEL,
/**
* A type that is a named member of another type.
* A class or interface that is a named member of another class or
* interface.
* @jls 8.5 Member Type Declarations
*/
MEMBER,
/**
* A named type declared within a construct other than a type.
* A named class or interface declared within a construct other
* than a class or interface.
* @jls 14.3 Local Class Declarations
*/
LOCAL,
/**
* A type without a name.
* A class without a name.
* @jls 15.9.5 Anonymous Class Declarations
*/
ANONYMOUS;

2
src/java.compiler/share/classes/javax/lang/model/element/RecordComponentElement.java
View File

@ -34,7 +34,7 @@ public interface RecordComponentElement extends Element {
/**
* {@return the enclosing element of this record component}
*
* The enclosing element of a record component is the type
* The enclosing element of a record component is the record class
* declaring the record component.
*/
@Override

71
src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
View File

@ -31,8 +31,9 @@ import javax.lang.model.util.*;
/**
* Represents a class or interface program element. Provides access
* to information about the type and its members. Note that an enum
* type and a record type are kinds of classes and an annotation type is a kind of
* to information about the class or interface and its members. Note
* that an enum class and a record class are specialized kinds of
* classes and an annotation interface is a specialized kind of
* interface.
*
* <p> While a {@code TypeElement} represents a class or interface
@ -60,8 +61,9 @@ import javax.lang.model.util.*;
*/
public interface TypeElement extends Element, Parameterizable, QualifiedNameable {
/**
* Returns the type defined by this type element, returning the
* <i>prototypical</i> type for an element representing a generic type.
* Returns the type defined by this class or interface element,
* returning the <i>prototypical</i> type for an element
* representing a generic type.
*
* <p>A generic element defines a family of types, not just one.
* If this is a generic element, a prototypical type is
@ -83,24 +85,24 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
/**
* Returns the fields, methods, constructors, record components,
* and member types that are directly declared in this class or
* interface.
* and member classes and interfaces that are directly declared in
* this class or interface.
*
* This includes any {@linkplain Elements.Origin#MANDATED
* mandated} elements such as the (implicit) default constructor
* and the implicit {@code values} and {@code valueOf} methods of
* an enum type.
* an enum class.
*
* @apiNote As a particular instance of the {@linkplain
* javax.lang.model.element general accuracy requirements} and the
* ordering behavior required of this interface, the list of
* enclosed elements will be returned in the natural order for the
* originating source of information about the type. For example,
* if the information about the type is originating from a source
* file, the elements will be returned in source code order.
* (However, in that case the ordering of {@linkplain
* Elements.Origin#MANDATED implicitly declared} elements, such as
* default constructors, is not specified.)
* originating source of information about the class or interface.
* For example, if the information about the class or interface is
* originating from a source file, the elements will be returned
* in source code order. (However, in that case the ordering of
* {@linkplain Elements.Origin#MANDATED implicitly declared}
* elements, such as default constructors, is not specified.)
*
* @return the enclosed elements in proper order, or an empty list if none
*
@ -111,23 +113,24 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
List<? extends Element> getEnclosedElements();
/**
* Returns the <i>nesting kind</i> of this type element.
* Returns the <i>nesting kind</i> of this class or interface element.
*
* @return the nesting kind of this type element
* @return the nesting kind of this class or interface element
*/
NestingKind getNestingKind();
/**
* Returns the fully qualified name of this type element. More
* precisely, it returns the <i>canonical</i> name. For local and
* anonymous classes, which do not have canonical names, an <a
* href=Name.html#empty_name>empty name</a> is returned.
* Returns the fully qualified name of this class or interface
* element. More precisely, it returns the <i>canonical</i> name.
* For local and anonymous classes, which do not have canonical
* names, an <a href=Name.html#empty_name>empty name</a> is
* returned.
*
* <p>The name of a generic type does not include any reference
* <p>The name of a generic class or interface does not include any reference
* to its formal type parameters.
* For example, the fully qualified name of the interface
* {@code java.util.Set<E>} is "{@code java.util.Set}".
* Nested types use "{@code .}" as a separator, as in
* Nested classes and interfaces use "{@code .}" as a separator, as in
* "{@code java.util.Map.Entry}".
*
* @return the fully qualified name of this class or interface, or
@ -139,7 +142,7 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
Name getQualifiedName();
/**
* Returns the simple name of this type element.
* Returns the simple name of this class or interface element.
*
* For an anonymous class, an <a href=Name.html#empty_name> empty
* name</a> is returned.
@ -152,8 +155,8 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
Name getSimpleName();
/**
* Returns the direct superclass of this type element.
* If this type element represents an interface or the class
* Returns the direct superclass of this class or interface element.
* If this class or interface element represents an interface or the class
* {@code java.lang.Object}, then a {@link NoType}
* with kind {@link TypeKind#NONE NONE} is returned.
*
@ -171,7 +174,7 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
List<? extends TypeMirror> getInterfaces();
/**
* Returns the formal type parameters of this type element
* Returns the formal type parameters of this class or interface element
* in declaration order.
*
* @return the formal type parameters, or an empty list
@ -180,8 +183,8 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
List<? extends TypeParameterElement> getTypeParameters();
/**
* Returns the record components of this type element in
* declaration order.
* Returns the record components of this class or interface
* element in declaration order.
*
* @implSpec The default implementations of this method returns an
* empty and unmodifiable list.
@ -202,8 +205,8 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
* feature of the Java language. Preview features
* may be removed in a future release, or upgraded to permanent
* features of the Java language.}
* Returns the permitted classes of this type element in
* declaration order.
* Returns the permitted classes of this class or interface
* element in declaration order.
*
* @implSpec The default implementations of this method returns an
* empty and unmodifiable list.
@ -219,12 +222,12 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
}
/**
* Returns the package of a top-level type and returns the
* immediately lexically enclosing element for a {@linkplain
* NestingKind#isNested nested} type.
* Returns the package of a top-level class or interface and
* returns the immediately lexically enclosing element for a
* {@linkplain NestingKind#isNested nested} class or interface.
*
* @return the package of a top-level type, the immediately
* lexically enclosing element for a nested type
* @return the package of a top-level class or interface, the immediately
* lexically enclosing element for a nested class or interface
*/
@Override
Element getEnclosingElement();

32
src/java.compiler/share/classes/javax/lang/model/element/package-info.java
View File

@ -50,7 +50,9 @@
* recovered from class files and class files might not be able to
* provide source position information.
*
* Names of {@linkplain javax.lang.model.element.ExecutableElement#getParameters() parameters} may not be recoverable from class files.
* Names of {@linkplain
* javax.lang.model.element.ExecutableElement#getParameters()
* parameters} may not be recoverable from class files.
*
* The {@linkplain javax.lang.model.element.Modifier modifiers} on an
* element created from a class file may differ in some cases from an
@ -82,20 +84,20 @@
* guarantees about the nature of the resulting model. If the source
* code is not syntactically well-formed or has some other
* irrecoverable error that could not be removed by the generation of
* new types, a model may or may not be provided as a quality of
* implementation issue.
* If a program is syntactically valid but erroneous in some other
* fashion, any returned model must have no less information than if
* all the method bodies in the program were replaced by {@code "throw
* new RuntimeException();"}. If a program refers to a missing type Xyz,
* the returned model must contain no less information than if the
* declaration of type Xyz were assumed to be {@code "class Xyz {}"},
* {@code "interface Xyz {}"}, {@code "enum Xyz {}"}, {@code
* "@interface Xyz {}"}, or {@code "record Xyz {}"}. If a program refers to a missing type {@code
* Xyz<K1, ... ,Kn>}, the returned model must contain no less
* information than if the declaration of Xyz were assumed to be
* {@code "class Xyz<T1, ... ,Tn> {}"} or {@code "interface Xyz<T1,
* ... ,Tn> {}"}
* new classes or interfaces, a model may or may not be provided as a
* quality of implementation issue. If a program is syntactically
* valid but erroneous in some other fashion, any returned model must
* have no less information than if all the method bodies in the
* program were replaced by {@code "throw new RuntimeException();"}.
* If a program refers to a missing class or interface Xyz, the
* returned model must contain no less information than if the
* declaration of class or interface Xyz were assumed to be {@code
* "class Xyz {}"}, {@code "interface Xyz {}"}, {@code "enum Xyz {}"},
* {@code "@interface Xyz {}"}, or {@code "record Xyz {}"}. If a
* program refers to a missing class or interface {@code Xyz<K1,
* ... ,Kn>}, the returned model must contain no less information than
* if the declaration of Xyz were assumed to be {@code "class Xyz<T1,
* ... ,Tn> {}"} or {@code "interface Xyz<T1, ... ,Tn> {}"}
*
* <p> Unless otherwise specified in a particular implementation, the
* collections returned by methods in this package should be expected

2
src/java.compiler/share/classes/javax/lang/model/util/ElementFilter.java
View File

@ -166,7 +166,7 @@ public class ElementFilter {
}
/**
* {@return a list of types in {@code elements}}
* {@return a list of classes and interfaces in {@code elements}}
* @param elements the elements to filter
*/
public static List<TypeElement>

16
src/java.compiler/share/classes/javax/lang/model/util/Elements.java
View File

@ -336,7 +336,7 @@ public interface Elements {
* An annotation mirror is {@linkplain Origin#MANDATED mandated}
* if it is an implicitly declared <em>container annotation</em>
* used to hold repeated annotations of a repeatable annotation
* type.
* interface.
*
* <p>Note that if this method returns {@link Origin#EXPLICIT
* EXPLICIT} and the annotation mirror was created from a class
@ -423,7 +423,7 @@ public interface Elements {
*
* Another example of a mandated construct is an implicitly
* declared <em>container annotation</em> used to hold
* multiple annotations of a repeatable annotation type.
* multiple annotations of a repeatable annotation interface.
*
* @jls 8.8.9 Default Constructor
* @jls 8.9.3 Enum Members
@ -480,7 +480,7 @@ public interface Elements {
* itself.
* The package of a module is {@code null}.
*
* The package of a top-level type is its {@linkplain
* The package of a top-level class or interface is its {@linkplain
* TypeElement#getEnclosingElement enclosing package}. Otherwise,
* the package of an element is equal to the package of the
* {@linkplain Element#getEnclosingElement enclosing element}.
@ -559,7 +559,7 @@ public interface Elements {
boolean hides(Element hider, Element hidden);
/**
* Tests whether one method, as a member of a given type,
* Tests whether one method, as a member of a given class or interface,
* overrides another method.
* When a non-abstract method overrides an abstract one, the
* former is also said to <i>implement</i> the latter.
@ -578,8 +578,8 @@ public interface Elements {
* </blockquote>
*
* A more interesting case can be illustrated by the following example
* in which a method in type {@code A} does not override a
* like-named method in type {@code B}:
* in which a method in class {@code A} does not override a
* like-named method in interface {@code B}:
*
* <blockquote>
* {@code class A { public void m() {} } }<br>
@ -591,7 +591,7 @@ public interface Elements {
* elements.getTypeElement("A")); }
* </blockquote>
*
* When viewed as a member of a third type {@code C}, however,
* When viewed as a member of a third class {@code C}, however,
* the method in {@code A} does override the one in {@code B}:
*
* <blockquote>
@ -603,7 +603,7 @@ public interface Elements {
*
* @param overrider the first method, possible overrider
* @param overridden the second method, possibly being overridden
* @param type the type of which the first method is a member
* @param type the class or interface of which the first method is a member
* @return {@code true} if and only if the first method overrides
* the second
* @jls 8.4.8 Inheritance, Overriding, and Hiding