Summary

Explicitly state conditions where Types.asElement() will return null.

Problem

The specification of Types.asElement() only implies the cases where the type does not have a corresponding element, and thus returns null.

Solution

Add a list of cases based on TypeKind, that definitely return null. Not all TypeKind constants are listed.

Specification

--- a/src/java.compiler/share/classes/javax/lang/model/util/Types.java
+++ b/src/java.compiler/share/classes/javax/lang/model/util/Types.java
@@ -45,10 +45,22 @@

     /**
      * Returns the element corresponding to a type.
-     * The type may be a {@code DeclaredType} or {@code TypeVariable}.
+     * The type may be a {@link DeclaredType} or {@link TypeVariable},
+     * or a pseudo-type for a {@linkplain TypeKind#PACKAGE package} or
+     * {@linkplain TypeKind#MODULE module}.
      * Returns {@code null} if the type is not one with a
      * corresponding element.
      *
+     * <p>Types <em>without</em> corresponding elements include:
+     * <ul>
+     * <li>{@linkplain TypeKind#isPrimitive() primitive types}
+     * <li>{@linkplain TypeKind#EXECUTABLE executable types}
+     * <li>{@linkplain TypeKind#NONE "none" pseudo-types}
+     * <li>{@linkplain TypeKind#NULL null types}
+     * <li>{@link TypeKind#VOID void}
+     * <li>{@linkplain TypeKind#WILDCARD wildcard type argument}
+     * </ul>
+     *
      * @param t the type to map to an element
      * @return the element corresponding to the given type
      */