8175386: Clarify exception behavior of Types utility methods

Reviewed-by: jjg
This commit is contained in:
Joe Darcy 2024-01-26 22:33:17 +00:00
parent 70f4a4e18e
commit 2e748c998e

@ -35,7 +35,18 @@ import javax.lang.model.type.*;
/**
* Utility methods for operating on types.
*
* Where a method returns a type mirror or a collection of type
* Most methods operate on {@linkplain PrimitiveType primitive types},
* {@linkplain ReferenceType reference types} (including {@linkplain
* ArrayType array types} and the {@linkplain NullType null type}),
* {@linkplain IntersectionType intersection types}, and the
* pseudo-type '{@link TypeKind#VOID void}'. {@linkplain
* ExecutableType Executable types} and the pseudo-types for
* {@linkplain TypeKind#PACKAGE packages} and {@linkplain
* TypeKind#MODULE modules} are generally out of scope for these
* methods. One or more out of scope arguments will typically result
* in a method throwing an {@link IllegalArgumentException}.
*
* <p>Where a method returns a type mirror or a collection of type
* mirrors, any type mirrors represent types with no type annotations,
* unless otherwise indicated.
*
@ -211,11 +222,13 @@ public interface Types {
*
* @param kind the kind of primitive type to return
* @throws IllegalArgumentException if {@code kind} is not a primitive kind
* @jls 4.2 Primitive Types and Values
*/
PrimitiveType getPrimitiveType(TypeKind kind);
/**
* {@return the null type} This is the type of {@code null}.
* @jls 4.1 The Kinds of Types and Values
*/
NullType getNullType();
@ -245,7 +258,8 @@ public interface Types {
*
* @param componentType the component type
* @throws IllegalArgumentException if the component type is not valid for
* an array
* an array, including executable, package, module, and wildcard types
* @jls 10.1 Array Types
*/
ArrayType getArrayType(TypeMirror componentType);
@ -258,6 +272,7 @@ public interface Types {
* @param extendsBound the extends (upper) bound, or {@code null} if none
* @param superBound the super (lower) bound, or {@code null} if none
* @throws IllegalArgumentException if bounds are not valid
* @jls 4.5.1 Type Arguments of Parameterized Types
*/
WildcardType getWildcardType(TypeMirror extendsBound,
TypeMirror superBound);