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

[ExE Boss]

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 758:

> 756:      * @param obj the reference to check, an object or {@code null}
> 757:      * @return true the reference type represented by this {@code Class} is
> 758:      *         a supertype of the class of {@code obj}; false otherwise

Missing “if”:
Suggestion:

     * @return true if the reference type represented by this {@code Class}
     *         is a supertype of the class of {@code obj}; false otherwise

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

PR Review Comment: https://git.openjdk.org/jdk/pull/28684#discussion_r2637236468