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

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

> 32:  * recognized by {@code vmIntrinsics.hpp} and may be subject to intrinsification
> 33:  * by the HotSpot VM (see {@code LibraryCallKit::try_to_inline} in {@code
> 34:  * library_call.cpp}) if an intrinsic is available.  Intrinsification replaces a

This lead sentence is too long to read conveniently, partly because it is broken up by a parenthetical.

Suggest:


The `@IntrinsicCandidate` indicates that an annotated method is
recognized by `vmIntrinsics.hpp` and may be subject to intrinsification
by the HotSpot VM.  (See `LibraryCallKit::try_to_inline` in `library_call.cpp`
for logic that checks if an intrinsic is available and applicable at a given call site.)

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

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