Summary

Clarify handling of invalid inputs by Types.{unboxedType, getWildcardType}.

Problem

The existing exception case specification for these methods is terse and does not explicitly state cases which could expected to be exceptional.

Solution

Add more detail on exceptional cases.

Specification

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 266d63178ba..232e15a84bd 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
@@ -50,6 +50,11 @@
  * <p><b>Compatibility Note:</b> Methods may be added to this interface
  * in future releases of the platform.
  *
+ * @apiNote
+ * In the reference implementation, handling {@linkplain ErrorType
+ * error types} generally does not cause an {@code
+ * IllegalArgumentException} from the methods in this interface.
+ *
  * @see javax.annotation.processing.ProcessingEnvironment#getTypeUtils
  * @since 1.6
  */
@@ -198,8 +203,10 @@ public interface Types {
      *
      * @param t  the type to be unboxed
      * @return the type of an unboxed value of type {@code t}
+     *
      * @throws IllegalArgumentException if the given type has no
-     *          unboxing conversion
+     *         unboxing conversion. Only types for the wrapper classes
+     *         have an unboxing conversion.
      * @jls 5.1.8 Unboxing Conversion
      */
     PrimitiveType unboxedType(TypeMirror t);
@@ -268,7 +275,10 @@ 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
+     *
+     * @throws IllegalArgumentException if bounds are not valid. Invalid bounds
+     * include all types that are not {@linkplain ReferenceType
+     * reference types}.
      * @jls 4.5.1 Type Arguments of Parameterized Types
      */
     WildcardType getWildcardType(TypeMirror extendsBound,