8175386: Clarify exception behavior of Types utility methods

Reviewed-by: jjg

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