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. ------------- Commit messages: - Improve documentation of Class.isInstance Changes: https://git.openjdk.org/jdk/pull/28684/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=28684&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8371795 Stats: 90 lines in 1 file changed: 35 ins; 16 del; 39 mod Patch: https://git.openjdk.org/jdk/pull/28684.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/28684/head:pull/28684 PR: https://git.openjdk.org/jdk/pull/28684
