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

[John R Rose]

On Wed, 30 Apr 2025 22:26:30 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 eight additional commits since the last revision:
> 
>  - 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
>  - Refine validation and defensive copying
>  - 8355223: Improve documentation on @IntrinsicCandidate

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

> 31:  * The {@code @IntrinsicCandidate} indicates that an annotated method is
> 32:  * recognized by {@code vmIntrinsics.hpp} for special treatment by the HotSpot
> 33:  * VM, unlike the other methods.  The HotSpot VM checks, when loading a class,

/, unlike the other methods/s/the other/other/

If you want something at the top that teaches about "the other methods", maybe say something like:

> Normally, the VM executes methods using only their bytecodes (or JNI definitions), but the VM is (in addition) allowed to use specialized code or analysis logic for methods marked as intrinsics.  Thus, intrinsic calls can be replaced or modified or specially optimized by the VM.

But those points will be covered further down, so maybe not.

More concisely:  s/, unlike the other methods/, unlike normal methods, which depend only on bytecodes or native entry points for their meaning to the VM/

Or just: s/, unlike the other methods//

Also, s/The HotSpot VM checks, when loading a class,/When loading a class, the HotSpot VM checks/ (fewer commas, better logical flow)

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

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