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

[Raffaello Giulietti]

On Tue, 22 Apr 2025 21:57:19 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:
> 
>   Shorter first sentence

src/java.base/share/classes/jdk/internal/vm/annotation/IntrinsicCandidate.java line 70:

> 68:  * accessed by the current thread: shared fields must be read into local
> 69:  * variables, and shared arrays must be copied to an exclusive copy, to ensure
> 70:  * each shared location (a field or an array component) is accessed exactly once.

Suggestion:

 * each shared location (a field or an array component) is accessed at most once.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24777#discussion_r2056018522