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

[Joe Darcy]

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

Perhaps as part of a larger doc refresh, there would be a section at the top of Class comparing and contrasting this set of related methods.

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

PR Comment: https://git.openjdk.org/jdk/pull/28684#issuecomment-3730307487