archive/jdk
1
0
Fork 0
mirror of https://github.com/openjdk/jdk.git synced 2025-08-28 15:24:43 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

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
Download patch file Download diff file Expand all files Collapse all files

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