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

[John R Rose]

On Tue, 22 Apr 2025 21:01:13 GMT, Chen Liang <liach at openjdk.org> wrote:

>> In the new design, the above "footnotes" go at the bottom.  They explain why the rules prescribed at the top are important.  In effect, inform aggressive implementors how far they may bend those rules.  Sometimes the rules do get bent, sometimes to allow unspecified behavior, but never so far as to allow a type safety violation.
>
> I still believe these information are important and better kept inline; inlined them with blockquote tags.

+1 from me on your preference.  In formulating footnotes I was trying to respect your attempt to put the most important bits at the top.  I actually prefer the "sidebars" (what you have) to "footnotes".

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

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