Intro and other various improvements

src/java.base/share/classes/java/lang/reflect/AnnotatedParameterizedType.java

@@ -68,7 +68,7 @@ public interface AnnotatedParameterizedType extends AnnotatedType {
      * {@return the potentially annotated use of the immediately enclosing class
      * of the parameterized type, or {@code null} if and only if the
      * parameterized type is not an inner member class}  For example, if this
-     * use is {@code Outer<@TC Long>.@TA nner<@TB String>}, this method returns
+     * use is {@code Outer<@TC Long>.@TA Inner<@TB String>}, this method returns
      * a representation of {@code Outer<@TC Long>}.
      *
      * @throws TypeNotPresentException {@inheritDoc}

src/java.base/share/classes/java/lang/reflect/AnnotatedType.java

@@ -28,38 +28,45 @@
 import java.lang.annotation.Annotation;
 
 /**
- * {@code AnnotatedType} represents the potentially annotated (JLS {@jls 9.7.4})
- * use of a type or type argument in the current runtime. See {@link Type} for
- * the complete list of types and type arguments.
- * <p>
- * Here is a mapping from types and type arguments of the use, with examples,
- * to the modeling interfaces. "{@code AnnotatedType} alone" means the modeling
- * class does not implement any of the subinterfaces of {@code AnnotatedType}.
- * <ul>
- * <li>Primitive types (such as {@code @TA int}):
- *     {@code AnnotatedType} alone
- * <li>Reference types: <ul>
- *     <li>Class types and interface types:<ul>
- *         <li>Parameterized types (such as {@code @TA List<@TB ? extends @TC
- *             String>}): {@link AnnotatedParameterizedType}
- *         <li>Non-generic classes and interfaces (such as {@code @TC String})
- *             and raw types (such as {@code @TA List}):
- *             {@code AnnotatedType} alone
- *     </ul>
- *     <li>Type variables (such as {@code @TA T}):
- *         {@link AnnotatedTypeVariable}
- *     <li>Array types (such as {@code @TB int @TA []}):
- *         {@link AnnotatedArrayType}
- * </ul>
- * <li>Wildcard type arguments (such as {@code @TB ? extends @TC String}):
- *     {@link AnnotatedWildcardType}
- * </ul>
- * <p>
- * For example, an annotated use {@code @TB Outer.@TA Inner}, represented by
- * {@code AnnotatedType} alone, has an annotation {@code @TA} and represents the
- * non-generic {@code Outer.Inner} class. The use of its immediately enclosing
- * class is {@code @TB Outer}, with an annotation {@code @TB}, representing the
- * non-generic {@code Outer} class.
+ * {@code AnnotatedType} represents the potentially annotated use of a type or
+ * type argument in the current runtime.  The use of a type (JLS {@jls 4.1}) is
+ * the use of a primitive type or a reference type.  The use of a type argument
+ * (JLS {@jls 4.5.1}) is the use of a reference type or a wildcard type
+ * argument.
+ * <table class="striped">
+ * <caption style="display:none">
+ * Types and Type Arguments Used to Modeling Interfaces
+ * </caption>
+ * <thead>
+ * <tr><th colspan="3">Type or Type Argument Used
+ *     <th>Example
+ *     <th>Modeling interface
+ * </thead>
+ * <tbody>
+ * <tr><td colspan="3">Primitive Types (JLS {@jls 4.2})
+ *     <td>{@code @TA int}
+ *     <td rowspan="3">{@link ##alone AnnotatedType}
+ * <tr><td rowspan="5">Reference<br>Types<br>(JLS {@jls 4.3})
+ *     <td rowspan="3">Classes<br>and<br>Interfaces
+ *     <td>Non-generic Classes and<br>Interfaces
+ *         (JLS {@jls 8.1.3}, {@jls 9.1.3})
+ *     <td>{@code @TC String}
+ * <tr><td>Raw Types (JLS {@jls 4.8})
+ *     <td>{@code @TA List}
+ * <tr><td>Parameterized Types (JLS {@jls 4.5})
+ *     <td>{@code @TA List<@TB ? extends @TC String>}
+ *     <td>{@link AnnotatedParameterizedType}
+ * <tr><td colspan="2">Type Variables (JLS {@jls 4.4})
+ *     <td>{@code @TA T}
+ *     <td>{@link AnnotatedTypeVariable}
+ * <tr><td colspan="2">Array Types (JLS {@jls 10.1})
+ *     <td>{@code @TB int @TA []}
+ *     <td>{@link AnnotatedArrayType}
+ * <tr><td colspan="3">Wildcard Type Arguments (JLS {@jls 4.5.1})
+ *     <td>{@code @TB ? extends @TC String}
+ *     <td>{@link AnnotatedWildcardType}
+ * </tbody>
+ * </table>
  * <p>
  * Note that any annotations returned by methods on this interface are
  * <em>type annotations</em> (JLS {@jls 9.7.4}) as the entity being
@@ -68,15 +75,22 @@
  * Two {@code AnnotatedType} objects should be compared using the {@link
  * Object#equals equals} method.
  *
+ * <h2 id="alone">The {@code AnnotatedType} interface alone</h2>
+ * Some {@code AnnotatedType} objects are not instances of the {@link
+ * AnnotatedArrayType}, {@link AnnotatedParameterizedType}, {@link
+ * AnnotatedTypeVariable}, or {@link AnnotatedWildcardType} subinterfaces.
+ * Such a potentially annotated use represents a primitive type, a non-generic
+ * class or interface, or a raw type, and the {@link #getType() getType()}
+ * method returns a {@link Class}.
+ * <p>
+ * For example, an annotated use {@code @TB Outer.@TA Inner} has an annotation
+ * {@code @TA} and represents the non-generic {@code Outer.Inner} class. The use
+ * of its immediately enclosing class is {@code @TB Outer}, with an annotation
+ * {@code @TB}, representing the non-generic {@code Outer} class.
+ *
  * @see Type
- * @jls 4.1 The Kinds of Types and Values
- * @jls 4.2 Primitive Types and Values
- * @jls 4.3 Reference Types and Values
- * @jls 4.4 Type Variables
- * @jls 4.5 Parameterized Types
- * @jls 4.8 Raw Types
- * @jls 4.9 Intersection Types
- * @jls 10.1 Array Types
+ * @jls 4.11 Where Types Are Used
+ * @jls 9.7.4 Where Annotations May Appear
  * @since 1.8
  */
 public interface AnnotatedType extends AnnotatedElement {
@@ -106,9 +120,11 @@ default AnnotatedType getAnnotatedOwnerType() {
     /**
      * {@return the type that this potentially annotated use represents}
      * <p>
-     * If this object does not implement any of the subinterfaces of {@code
-     * AnnotatedType}, this use represents a primitive type, a non-generic class
-     * or interface, or a raw type, and this method returns a {@link Class}.
+     * If this object is not an instance of {@link AnnotatedArrayType}, {@link
+     * AnnotatedParameterizedType}, {@link AnnotatedTypeVariable}, or {@link
+     * AnnotatedWildcardType}, this method returns a {@link Class}.
+     *
+     * @see ##alone The {@code AnnotatedType} interface alone
      */
     Type getType();
 

src/java.base/share/classes/java/lang/reflect/AnnotatedTypeVariable.java

@@ -54,6 +54,11 @@ public interface AnnotatedTypeVariable extends AnnotatedType {
      * // @end
      * }
      *
+     * @throws TypeNotPresentException if any of the bounds refers to a
+     *     non-existent type declaration
+     * @throws MalformedParameterizedTypeException if any of the bounds refer to
+     *     a parameterized type that cannot be instantiated for any reason
+     * @jls 4.9 Intersection Types
      * @see TypeVariable#getAnnotatedBounds()
      * @see TypeVariable#getBounds()
      */

src/java.base/share/classes/java/lang/reflect/AnnotatedWildcardType.java

@@ -28,9 +28,11 @@
 /**
  * {@code AnnotatedWildcardType} represents the potentially annotated use of a
  * wildcard type argument, whose upper or lower bounds may themselves represent
- * annotated uses of types.  Note that the use of a wildcard type argument is
- * not the use of a type, and thus will only be returned by APIs where uses of
- * type arguments may appear.
+ * annotated uses of types.  Since the use of a wildcard type argument is not
+ * the use of a type, it will only be returned by APIs where uses of type
+ * arguments may appear, such as {@link
+ * AnnotatedParameterizedType#getAnnotatedActualTypeArguments()
+ * AnnotatedParameterizedType::getAnnotatedActualTypeArguments}.
  * <p>
  * For example, an annotated use {@code @TA ? extends @TB Number} has an
  * annotation {@code @TA} and represents the wildcard type argument {@code ?

src/java.base/share/classes/java/lang/reflect/Type.java

@@ -26,58 +26,70 @@
 package java.lang.reflect;
 
 /**
- * {@code Type} represents types in the Java programming language (JLS {@jls
- * 4.1}) and type arguments (JLS {@jls 4.5.1}).  Types are primitive types (JLS
- * {@jls 4.2}) and reference types (JLS {@jls 4.3}).  Reference types are
- * non-generic classes (JLS {@jls 8.1.2}) (which must not be an {@linkplain
- * ParameterizedType##inner-member-class inner member class} of a generic class)
- * and interfaces (JLS {@jls 9.1.2}), raw types (JLS {@jls 4.8}) and
- * parameterized types (JLS {@jls 4.5}) of generic classes and interfaces,
- * type variables (JLS {@jls 4.4}), and array types (JLS {@jls 10.1}).  Type
- * arguments are reference types and wildcard type arguments.
- * <p>
- * Here is a mapping from types and type arguments to the modeling interfaces.
- * "{@code Type} alone" means the modeling class does not implement any other
- * {@code Type} subinterface.  The modeling class is {@link Class} in core
- * reflection representation of types in the current runtime.  Other
- * implementations may use different modeling classes to represent types not
- * in the current runtime.
- * <ul>
- * <li>Primitive types (such as {@code int}): {@code Type} alone
- * <li>Reference types: <ul>
- *     <li>Class types and interface types:<ul>
- *         <li>Parameterized types (such as {@code List<String>}):
- *             {@link ParameterizedType}
- *         <li>Non-generic classes and interfaces (such as {@code String}) and
- *             raw types (such as {@code List}): {@code Type} alone
- *     </ul>
- *     <li>Type variables (such as {@code T}): {@link TypeVariable}
- *     <li>Array types: Depends on its element type. <ul>
- *         <li>If the element type is modeled by {@code Type} alone, such as
- *             {@code int} for the array type {@code int[]}, the array type is
- *             modeled by {@code Type} alone.
- *         <li>Otherwise, the element type must be modeled by {@link
- *             ParameterizedType}, such as {@code Comparable<?>} for the array
- *             type {@code Comparable<?>[]}, or {@link TypeVariable}, such as
- *             {@code T} for the array type {@code T[]}, and the array type is
- *             modeled by {@link GenericArrayType}.
- *     </ul>
- * </ul>
- * <li>Wildcard type arguments (such as {@code ? extends String}):
- *     {@link WildcardType}
- * </ul>
+ * {@code Type} represents types in the Java programming language and type
+ * arguments.  Types (JLS {@jls 4.1}) are primitive types and reference types.
+ * Type arguments (JLS {@jls 4.5.1}) are reference types and wildcard type
+ * arguments.
+ * <table class="striped">
+ * <caption style="display:none">
+ * Types and Type Arguments to Modeling Interfaces
+ * </caption>
+ * <thead>
+ * <tr><th colspan="3">Type or Type Argument
+ *     <th>Example
+ *     <th>Modeling interface
+ * </thead>
+ * <tbody>
+ * <tr><td colspan="3">Primitive Types (JLS {@jls 4.2})
+ *     <td>{@code int}
+ *     <td rowspan="3">{@link ##alone Type}
+ * <tr><td rowspan="9">Reference<br>Types<br>(JLS {@jls 4.3})
+ *     <td rowspan="3">Classes<br>and<br>Interfaces
+ *     <td>Non-generic Classes and<br>Interfaces
+ *         (JLS {@jls 8.1.3}, {@jls 9.1.3})
+ *     <td>{@code String}
+ * <tr><td>Raw Types (JLS {@jls 4.8})
+ *     <td>{@code List}
+ * <tr><td>Parameterized Types (JLS {@jls 4.5})
+ *     <td>{@code List<String>}
+ *     <td>{@link ParameterizedType}
+ * <tr><td colspan="2">Type Variables (JLS {@jls 4.4})
+ *     <td>{@code T}
+ *     <td>{@link TypeVariable}
+ * <tr><td rowspan="5">Array<br>Types<br>(JLS {@jls 10.1})
+ *     <td>Primitive Type Elements
+ *     <td>{@code int[]}
+ *     <td rowspan="3">{@link ##alone Type}
+ * <tr><td>Non-generic Class or<br>Interface Elements
+ *     <td>{@code String[]}
+ * <tr><td>Raw Type Elements
+ *     <td>{@code List[]}
+ * <tr><td>Parameterized Type Elements
+ *     <td>{@code List<String>[][]}
+ *     <td rowspan="2">{@link GenericArrayType}
+ * <tr><td>Types Variable Elements
+ *     <td>{@code T[][][]}
+ * <tr><td colspan="3">Wildcard Type Arguments (JLS {@jls 4.5.1})
+ *     <td>{@code ? extends String}
+ *     <td>{@link WildcardType}
+ * </tbody>
+ * </table>
  * <p>
  * Two {@code Type} objects should be compared using the {@link Object#equals
  * equals} method.
  *
+ * <h2 id="alone">The {@code Type} interface alone</h2>
+ * Some {@code Type} objects are not instances of the {@link GenericArrayType},
+ * {@link ParameterizedType}, {@link TypeVariable}, or {@link WildcardType}
+ * subinterfaces.  Such a type is a primitive type, a non-generic class or
+ * interface, a raw type, or an array type with any of these types as its
+ * element type.  In core reflection, they are all represented by {@link Class}.
+ * <p>
+ * Examples include the primitive type {@code int}, the non-generic {@link
+ * Object} class, the raw type {@code List}, and the array type {@code int[]}.
+ *
  * @jls 4.1 The Kinds of Types and Values
- * @jls 4.2 Primitive Types and Values
- * @jls 4.3 Reference Types and Values
- * @jls 4.4 Type Variables
- * @jls 4.5 Parameterized Types
- * @jls 4.8 Raw Types
- * @jls 4.9 Intersection Types
- * @jls 10.1 Array Types
+ * @jls 4.11 Where Types Are Used
  * @since 1.5
  */
 public interface Type {

src/java.base/share/classes/java/lang/reflect/TypeVariable.java

@@ -60,6 +60,7 @@ public interface TypeVariable<D extends GenericDeclaration> extends Type, Annota
      *     non-existent type declaration
      * @throws MalformedParameterizedTypeException if any of the bounds refer to
      *     a parameterized type that cannot be instantiated for any reason
+     * @jls 4.9 Intersection Types
      */
     Type[] getBounds();
 
@@ -81,6 +82,11 @@ public interface TypeVariable<D extends GenericDeclaration> extends Type, Annota
      * this method returns an array containing exactly the unannotated use of
      * the {@code Object} class.
      *
+     * @throws TypeNotPresentException if any of the bounds refers to a
+     *     non-existent type declaration
+     * @throws MalformedParameterizedTypeException if any of the bounds refer to
+     *     a parameterized type that cannot be instantiated for any reason
+     * @jls 4.9 Intersection Types
      * @since 1.8
      */
     AnnotatedType[] getAnnotatedBounds();

src/java.base/share/classes/java/lang/reflect/WildcardType.java

@@ -28,8 +28,9 @@
 /**
  * {@code WildcardType} represents a wildcard type argument, such as {@code ?},
  * {@code ? extends Number}, or {@code ? super Integer}.  Since a wildcard type
- * argument is not a type, and it will only be returned by APIs where type
- * arguments may appear.
+ * argument is not a type, it will only be returned by APIs where type arguments
+ * may appear, such as {@link ParameterizedType#getActualTypeArguments()
+ * ParameterizedType::getActualTypeArguments}.
  * <p>
  * Two {@code WildcardType} objects should be compared using the {@link
  * Object#equals equals} method.