From 2e748c998ee490d8c3b1c7ab2fadfcb4596fc07b Mon Sep 17 00:00:00 2001
From: Joe Darcy <darcy@openjdk.org>
Date: Fri, 26 Jan 2024 22:33:17 +0000
Subject: [PATCH] 8175386: Clarify exception behavior of Types utility methods

Reviewed-by: jjg
---
 .../classes/javax/lang/model/util/Types.java  | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/java.compiler/share/classes/javax/lang/model/util/Types.java b/src/java.compiler/share/classes/javax/lang/model/util/Types.java
index 93b43c777be50..f6296050ca9f5 100644
--- a/src/java.compiler/share/classes/javax/lang/model/util/Types.java
+++ b/src/java.compiler/share/classes/javax/lang/model/util/Types.java
@@ -35,7 +35,18 @@
 /**
  * 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);