From 6445314fec25b85db32d9fb75c9c1b29e07f01cb Mon Sep 17 00:00:00 2001
From: Joe Darcy <darcy@openjdk.org>
Date: Thu, 17 Aug 2023 20:25:46 +0000
Subject: [PATCH] 8314477: Improve definition of "prototypical type"

Reviewed-by: prappo
---
 .../classes/javax/lang/model/element/TypeElement.java     | 8 +++++++-
 .../share/classes/javax/lang/model/package-info.java      | 8 ++------
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java b/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
index 48bc4132eea..b99903a03fe 100644
--- a/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
+++ b/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java
@@ -88,7 +88,7 @@ import javax.lang.model.util.*;
 public interface TypeElement extends Element, Parameterizable, QualifiedNameable {
     /**
      * Returns the type defined by this class or interface element,
-     * returning the <i>prototypical</i> type for an element
+     * returning the <dfn>{@index "prototypical type"}</dfn> for an element
      * representing a generic type.
      *
      * <p>A generic element defines a family of types, not just one.
@@ -98,6 +98,12 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
      * For example,
      * for the generic class element {@code C<N extends Number>},
      * the parameterized type {@code C<N>} is returned.
+     * Otherwise, for a non-generic class or interface, the
+     * prototypical type mirror corresponds to a use of the type.
+     * None of the components of the prototypical type are annotated,
+     * including the prototypical type itself.
+     *
+     * @apiNote
      * The {@link Types} utility interface has more general methods
      * for obtaining the full range of types defined by an element.
      *
diff --git a/src/java.compiler/share/classes/javax/lang/model/package-info.java b/src/java.compiler/share/classes/javax/lang/model/package-info.java
index 5377b48065d..9df3e7f3b0a 100644
--- a/src/java.compiler/share/classes/javax/lang/model/package-info.java
+++ b/src/java.compiler/share/classes/javax/lang/model/package-info.java
@@ -114,12 +114,8 @@
  * javax.lang.model.element.Element#asType() mapped to} some type.
  * The elements for classes and interfaces get {@linkplain
  * javax.lang.model.element.TypeElement#asType() mapped to} a
- * prototypical type.  (If a class or interface is generic, its
- * prototypical type mirror is parameterized with type arguments
- * matching the type variables of the declaration, all
- * unannotated. Otherwise, for a non-generic class or interface, the
- * prototypical type mirror corresponds to an unannotated use of the
- * type.)  Conversely, in general, many types can map to the same
+ * {@linkplain javax.lang.model.element.TypeElement#asType() prototypical type}.
+ * Conversely, in general, many types can map to the same
  * {@linkplain javax.lang.model.element.TypeElement type element}. For
  * example, the type mirror for the raw type {@code java.util.Set},
  * the prototypical type {@code java.util.Set<E>}, and the type {@code