Summary

Update ParameterizedType.getOwnerType() and AnnotatedType.getOwnerType() docs to indicate they can return null, and top-level or local class or interface and anonymous class are (but not necessarily the only) scenarios where they do.

Problem

1. ParameterizedType.getOwnerType() may return null, and it does so for top level classes or interfaces, anonymous classes, and local classes or interfaces. However, the specification appears like null can only be returned for top-level classes or interfaces.
2. AnnotatedParameterizedType.getOwnerType() note describes an impossible scenario where it represents a primitive type or void.

Solution

1. Specify that ParameterizedType.getOwnerType may return null, and list those classes or interfaces as scenarios that it always return null.
2. Clarify those scenarios to be "top-level or local class or interface or anonymous class".
3. Remove the impossible primitive or void scenario in AnnotatedParameterizedType.getOwnerType()'s note.

Specification

diff --git a/src/java.base/share/classes/java/lang/reflect/AnnotatedParameterizedType.java b/src/java.base/share/classes/java/lang/reflect/AnnotatedParameterizedType.java
index 1c62d3d131c..f6bd9d5dc3f 100644
--- a/src/java.base/share/classes/java/lang/reflect/AnnotatedParameterizedType.java
+++ b/src/java.base/share/classes/java/lang/reflect/AnnotatedParameterizedType.java
@@ -48,16 +48,13 @@ public interface AnnotatedParameterizedType extends AnnotatedType {
     AnnotatedType[] getAnnotatedActualTypeArguments();

     /**
-     * Returns the potentially annotated type that this type is a member of, if
-     * this type represents a nested type. For example, if this type is
+     * {@return the potentially annotated type that this type is a member of, if
+     * this type represents a nested type, or {@code null}} For example, if this type is
      * {@code @TA O<T>.I<S>}, return a representation of {@code @TA O<T>}.
      *
      * <p>Returns {@code null} if this {@code AnnotatedType} represents a
-     *     top-level class or interface, or a local or anonymous class, or
-     *     a primitive type, or void.
+     *     top-level or local class or interface or an anonymous class.
      *
-     * @return an {@code AnnotatedType} object representing the potentially
-     *     annotated type that this type is a member of, or {@code null}
      * @throws TypeNotPresentException if the owner type
      *     refers to a non-existent class or interface declaration
      * @throws MalformedParameterizedTypeException if the owner type
diff --git a/src/java.base/share/classes/java/lang/reflect/AnnotatedType.java b/src/java.base/share/classes/java/lang/reflect/AnnotatedType.java
index 9525d3638fd..bc563b731b6 100644
--- a/src/java.base/share/classes/java/lang/reflect/AnnotatedType.java
+++ b/src/java.base/share/classes/java/lang/reflect/AnnotatedType.java
@@ -50,12 +50,12 @@
 public interface AnnotatedType extends AnnotatedElement {

     /**
-     * Returns the potentially annotated type that this type is a member of, if
-     * this type represents a nested type. For example, if this type is
+     * {@return the potentially annotated type that this type is a member of, if
+     * this type represents a nested type, or {@code null}} For example, if this type is
      * {@code @TA O<T>.I<S>}, return a representation of {@code @TA O<T>}.
      *
      * <p>Returns {@code null} if this {@code AnnotatedType} represents a
-     *     top-level class or interface, or a local or anonymous class, or
+     *     top-level or local class or interface or an anonymous class, or
      *     a primitive type, or void.
      *
      * <p>Returns {@code null} if this {@code AnnotatedType} is an instance of
@@ -66,8 +66,6 @@ public interface AnnotatedType extends AnnotatedElement {
      * This default implementation returns {@code null} and performs no other
      * action.
      *
-     * @return an {@code AnnotatedType} object representing the potentially
-     *     annotated type that this type is a member of, or {@code null}
      * @throws TypeNotPresentException if the owner type
      *     refers to a non-existent class or interface declaration
      * @throws MalformedParameterizedTypeException if the owner type
diff --git a/src/java.base/share/classes/java/lang/reflect/ParameterizedType.java b/src/java.base/share/classes/java/lang/reflect/ParameterizedType.java
index 99016623a3e..0e42fe9079b 100644
--- a/src/java.base/share/classes/java/lang/reflect/ParameterizedType.java
+++ b/src/java.base/share/classes/java/lang/reflect/ParameterizedType.java
@@ -76,15 +76,14 @@ public interface ParameterizedType extends Type {
     Type getRawType();

     /**
-     * Returns a {@code Type} object representing the type that this type
-     * is a member of.  For example, if this type is {@code O<T>.I<S>},
+     * {@return a {@code Type} object representing the type that this type
+     * is a member of, or {@code null} if this type is not a member of
+     * another type}  For example, if this type is {@code O<T>.I<S>},
      * return a representation of {@code O<T>}.
      *
-     * <p>If this type is a top-level type, {@code null} is returned.
+     * <p>If this type is a top-level or local class or interface or
+     * an anonymous class, {@code null} is returned.
      *
-     * @return a {@code Type} object representing the type that
-     *     this type is a member of. If this type is a top-level type,
-     *     {@code null} is returned
      * @throws TypeNotPresentException if the owner type
      *     refers to a non-existent class or interface declaration
      * @throws MalformedParameterizedTypeException if the owner type