RFR: 8355223: Improve documentation on @IntrinsicCandidate [v3]

[John R Rose]

On Tue, 22 Apr 2025 20:58:21 GMT, Chen Liang <liach at openjdk.org> wrote:

>> In offline discussion, we noted that the documentation on this annotation does not recommend minimizing the intrinsified section and moving whatever can be done in Java to Java; thus I prepared this documentation update, to shrink a "TLDR" essay to something concise for readers, such as pointing to that list at `vmIntrinsics.hpp` instead of "a list".
>
> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Updates, thanks to John

FWIW I posted a formatted version here:
https://gist.github.com/rose00/b6f7b2d18bae20b9cd277672c05075b5

It made it easier for me to review, although it is likely to go out of date quickly.

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

PR Comment: https://git.openjdk.org/jdk/pull/24777#issuecomment-2822524512