RFR: 8371795: Improve documentation of Class.isInstance [v5]

[Aggelos Biboudis]

On Mon, 15 Dec 2025 16:04:10 GMT, Chen Liang <liach at openjdk.org> wrote:

>> The 3 methods to determine conversions and subtyping on `java.lang.Class`, which are `isInstance`, `cast`, and `isAssignableFrom`, have their documentation from the earliest days of the Java Platform. During the language evolution, a lot of terms have become inaccurate, such as "assignment-compatible", which does not apply for primitive types, and the out-of-date instanceof analogy with the upcoming patterns, in `isInstance`; `isAssignableFrom` is not very clear about arrays; `cast` would also benefit from more detailed explanations.
>> 
>> In my facelift, I moved the subtyping description to `isAssignableFrom`, and left the conversion stuff in `isInstance` and `cast`.  I intentionally avoided linking to too many JLS chapters to reduce confusions. I believe in this shape, we have a good amount of easily comprehensible yet accurate specification for all 3 methods, and users are welcome to read the linked JLS chapters for more details and context.
>
> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Stage

src/java.base/share/classes/java/lang/Class.java line 739:

> 737:      * Determines if the reference type represented by this {@code Class} object
> 738:      * is the same as or a proper supertype of the class of the object specified
> 739:      * by the argument.  This method is the dynamic equivalent of the type

What do you think about something like the following, just to minimize the diff with the original spec? 

"This method is the dynamic equivalent of the Java language {@code instanceof} type comparison operator (JLS {@jls15.20.2})"

(adding "type comparison" before the operator)

src/java.base/share/classes/java/lang/Class.java line 741:

> 739:      * by the argument.  This method is the dynamic equivalent of the type
> 740:      * comparison operator of the {@code instanceof} Java keyword (JLS {@jls
> 741:      * 15.20.2}).  This method returns {@code true} if and only if this {@code

I think this ("This method returns.... without throwing a {@code ClassCastException}") didn't need a change, did it? Because now it seems that `isInstance` checks only the success of a narrowing reference conversion. Because the following which is a widening reference conversion check returns `true` but it seems to be excluded by the new javadoc: `Animal.class.isInstance(new Dog())`.

src/java.base/share/classes/java/lang/Class.java line 748:

> 746:      * Class} object without throwing a {@code ClassCastException}.
> 747:      *
> 748:      * <p>This method behaves as if:

Showing an example is a great idea! Shouldn't we use an example with the actual `instanceof` type comparison operator here? Why use an example of `isAssignableFrom` to the `isInstance` javadoc?

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/28684#discussion_r2660767325
PR Review Comment: https://git.openjdk.org/jdk/pull/28684#discussion_r2661907375
PR Review Comment: https://git.openjdk.org/jdk/pull/28684#discussion_r2661912045