Summary

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

Problem

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

JavaDoc as a primary user of the DocTrees API does not allow references to primitive types in @see and {@link} tags. Unfortunately, it accepts references to array types with declared component type, generating a link to the component type. However, this is an edge case that is unlikely to occur in significant numbers as use of array types in this context was never propagated and does not make a lot of sense.

Other users of this API may rely on its current behavior, but they can also be considered edge cases and unlikely to occur in significant numbers.

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.

To alert developers who relied on the old behavior of this API, there should be a release note announcing the change in behavior.

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.

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..44d9bd89917 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
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2026, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -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);