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

[Chen Liang]

On Mon, 21 Apr 2025 20:12: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:
> 
>   Refine validation and defensive copying

I have incorporated these "footnote" as "blockquote" notes in the middle of the docs, immediately after their relevant paragraphs. Intellij renders them with extra indentation, which IMO has nice appearance.

Now, the docs have a few paragraphs:

1. Intro to intrinsics and intrinsification
2. Intrinsification can happen at any time, need consistency
3. Candidate methods and intrinsics - the arg assumptions are exported from intrinsics to candidate methods, callers fully responsible (footnote: list of type safety breaches)
4. Encapsulation of candidate with callers, and arg checks performed by callers (and array arg check perks)
5. VM also does consistency check for this annotation.

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

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