Summary

InstanceOfTree.getType() returns null in some cases, but its documentation does not say it does. The proposal herein is to document the existing behavior.

Problem

InstanceOfTree.getType() returns null in some cases, but its documentation does not say it does.

Solution

Enhance the InstanceOfTree.getType() documentation to specify when the method returns null. The existing behavior is not changed. The method returns null if the instanceof uses a pattern, and the pattern is not a type test (binding) pattern.

Alternatively, the method could attempt to return a non-null value for patterns, but the semantics is unclear for complex patterns.

Specification

This is the proposed change:

diff --git a/src/jdk.compiler/share/classes/com/sun/source/tree/InstanceOfTree.java b/src/jdk.compiler/share/classes/com/sun/source/tree/InstanceOfTree.java
index dfbf20f0640..793f4be1fc4 100644
--- a/src/jdk.compiler/share/classes/com/sun/source/tree/InstanceOfTree.java
+++ b/src/jdk.compiler/share/classes/com/sun/source/tree/InstanceOfTree.java
@@ -31,6 +31,8 @@
  * For example:
  * <pre>
  *   <em>expression</em> instanceof <em>type</em>
+ *
+ *   <em>expression</em> instanceof <em>pattern</em>
  * </pre>
  *
  * @jls 15.20.2 The instanceof Operator
@@ -48,32 +50,50 @@ public interface InstanceOfTree extends ExpressionTree {
     ExpressionTree getExpression();

     /**
-     * Returns the type for which to check, or {@code null} if this instanceof
+     * Returns the type for which to check, or {@code null} if this {@code instanceof}
      * uses a pattern other the {@link BindingPatternTree}.
      *
-     * @return the type or {@code null} if this instanceof uses a pattern other than
+     * <p>For {@code instanceof} without a pattern, i.e. in the following form:
+     * <pre>
+     *   <em>expression</em> instanceof <em>type</em>
+     * </pre>
+     * returns the type.
+     *
+     * <p>For {@code instanceof} with a {@link BindingPatternTree}, i.e. in the following form:
+     * <pre>
+     *   <em>expression</em> instanceof <em>type</em> <em>variable_name</em>
+     * </pre>
+     * returns the type.
+     *
+     * <p>For instanceof with a pattern, i.e. in the following form:
+     * <pre>
+     *   <em>expression</em> instanceof <em>pattern</em>
+     * </pre>
+     * returns {@code null}.
+     *
+     * @return the type or {@code null} if this {@code instanceof} uses a pattern other than
      *         the {@linkplain BindingPatternTree}
      * @see #getPattern()
      */
     Tree getType();

     /**
-     * Returns the tested pattern, or null if this instanceof does not use
+     * Returns the tested pattern, or {@code null} if this {@code instanceof} does not use
      * a pattern.
      *
      * <p>For instanceof with a pattern, i.e. in the following form:
      * <pre>
-     *   <em>expression</em> instanceof <em>type</em> <em>variable name</em>
+     *   <em>expression</em> instanceof <em>pattern</em>
      * </pre>
      * returns the pattern.
      *
-     * <p>For instanceof without a pattern, i.e. in the following form:
+     * <p>For {@code instanceof} without a pattern, i.e. in the following form:
      * <pre>
      *   <em>expression</em> instanceof <em>type</em>
      * </pre>
-     * returns null.
+     * returns {@code null}.
      *
-     * @return the tested pattern, or null if this instanceof does not use a pattern
+     * @return the tested pattern, or {@code null} if this {@code instanceof} does not use a pattern
      * @since 16
      */
     PatternTree getPattern();