Summary

Make the behavior of com.sun.source.util.DocTrees.getElement(DocTreePath) consistent with language model semantics and avoid leaking internal javac Symbols.

Problem

For historical reasons (support of @serialField tag before we had DocTrees.getType), the DocTrees.getElement(DocTreePath) method returns values that are not language model elements, such as for primitive types, and returns the component type for arrays.

Solution

Make DocTrees.getElement(DocTreePath) more consistent with the javax.lang.model specification by returning null if the referenced Symbol is a primitive or array type.

Improve the description of the DocTrees.getElement and DocTrees.getType methods to make their behavior clearer.

Specification

We add reciprocal @see tags to the documentation of DocTrees.getElement(DocTreePath) and DocTrees.getType(DocTreePath). The description of the relation between the two methods in DocTrees.getType(DocTreePath) is expanded as shown in the the diff below.

Although not directly related to this change, we also add array types to the list of explicitly unsupported types in javax.lang.model.util.Types.asElement(TypeMirror).

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 e7212a7e0be..61978e52648 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
@@ -75,6 +75,7 @@ public interface Types {
      * <ul>
      * <li>{@linkplain TypeKind#isPrimitive() primitive types}
      * <li>{@linkplain TypeKind#EXECUTABLE executable types}
+     * <li>{@linkplain TypeKind#ARRAY array types}
      * <li>{@linkplain TypeKind#NONE "none"} pseudo-types
      * <li>{@linkplain TypeKind#NULL null types}
      * <li>{@link TypeKind#VOID void}
diff --git a/src/jdk.compiler/share/classes/com/sun/source/util/DocTrees.java b/src/jdk.compiler/share/classes/com/sun/source/util/DocTrees.java
index 45a452bd0dd..5490f754620 100644
--- a/src/jdk.compiler/share/classes/com/sun/source/util/DocTrees.java
+++ b/src/jdk.compiler/share/classes/com/sun/source/util/DocTrees.java
@@ -195,23 +195,30 @@ public static DocTrees instance(ProcessingEnvironment env) {
 
     /**
      * Returns the language model element referred to by the leaf node of the given
-     * {@link DocTreePath}, or {@code null} if unknown.
+     * {@link DocTreePath}, or {@code null} if the leaf node of {@code path} does
+     * not refer to an element.
+     *
      * @param path the path for the tree node
-     * @return the element
+     * @return the referenced element, or null
+     * @see #getType(DocTreePath)
      */
     public abstract Element getElement(DocTreePath path);
 
     /**
      * Returns the language model type referred to by the leaf node of the given
-     * {@link DocTreePath}, or {@code null} if unknown. This method usually
-     * returns the same value as {@code getElement(path).asType()} for a
-     * {@code path} argument for which {@link #getElement(DocTreePath)} returns
-     * a non-null value, but may return a type that includes additional
-     * information, such as a parameterized generic type instead of a raw type.
+     * {@link DocTreePath}, or {@code null} if the leaf node of {@code path} does
+     * not refer to a type.
+     *
+     * <p>If {@link #getElement(DocTreePath)} returns a non-null value for a given {@code path}
+     * argument, this method usally returns the same value as {@code getElement(path).asType()}.
+     * However, there are cases where the returned type includes additional information,
+     * such as a parameterized generic type instead of a raw type. In other cases, such as with
+     * primitive or array types, the returned type may not have a corresponding element returned
+     * by {@code getElement(DocTreePath)}.</p>
      *
      * @param path the path for the tree node
      * @return the referenced type, or null
-     *
+     * @see #getElement(DocTreePath)
      * @since 15
      */
     public abstract TypeMirror getType(DocTreePath path);