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

[Roger Riggs]

On Wed, 23 Apr 2025 14:12:29 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:
> 
>   Update src/java.base/share/classes/jdk/internal/vm/annotation/IntrinsicCandidate.java
>   
>   Co-authored-by: Raffaello Giulietti <raffaello.giulietti at oracle.com>

I would also point out that IntrinsicCandidate has some off-label uses, in which the method is not replaced by the runtime but is just recognized as distinguished methods and identified for some optimization case.  The most common cases are related to the string concatenation subsystem, for example, StringBuilder.append(String). This might be covered under jrose00's more general comment a week ago.

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

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