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

[Roger Riggs]

On Fri, 19 Sep 2025 13:10:33 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 with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains 12 additional commits since the last revision:
> 
>  - Separate design doc
>  - Merge branch 'master' of https://github.com/openjdk/jdk into doc/intrinsic-candidate
>  - More review updates
>  - Merge branch 'master' of https://github.com/openjdk/jdk into doc/intrinsic-candidate
>  - Move intrinsic to be a subsection; just one most common function of the annotation
>  - Merge branch 'master' of https://github.com/openjdk/jdk into doc/intrinsic-candidate
>  - Merge branch 'master' of https://github.com/openjdk/jdk into doc/intrinsic-candidate
>  - Update src/java.base/share/classes/jdk/internal/vm/annotation/IntrinsicCandidate.java
>    
>    Co-authored-by: Raffaello Giulietti <raffaello.giulietti at oracle.com>
>  - Shorter first sentence
>  - Updates, thanks to John
>  - ... and 2 more: https://git.openjdk.org/jdk/compare/380c643a...e4afa49d

This seems more like guidance for people writing intrinsics and should be in the HotSpot part of the src tree. The annotation can link there.

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

> 40: /// what intrinsics are and cautions for working with annotated methods.
> 41: ///
> 42: /// @since 16

Lets stick to the javadoc /*... */ markup.

src/java.base/share/classes/jdk/internal/vm/annotation/intrinsics.md line 1:

> 1: <!--

Please remove the <cr> characters. LF line endings only please.

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

PR Review: https://git.openjdk.org/jdk/pull/24777#pullrequestreview-3247243759
PR Review Comment: https://git.openjdk.org/jdk/pull/24777#discussion_r2364599695
PR Review Comment: https://git.openjdk.org/jdk/pull/24777#discussion_r2364600305