[foreign-memaccess+abi] RFR: 8277945: Use snippets in jdk.incubator.foreign API documentation

[Maurizio Cimadamore]

On Mon, 29 Nov 2021 16:51:06 GMT, Julia Boes <jboes at openjdk.org> wrote:

> This change replaces `<pre>{@code ...}</pre>` blocks with the new `@snippet` tag.

I've tried the PR locally, and generated the javadoc. It looks beautiful. I left some comments on snippets which aren't really Java code, and which, I think, don't look too good in the snippet format. At the very least we should not treat them as lang=java snippet - but I wonder if the javadoc was better for these formulas in the way it was before.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java line 333:

> 331:      *
> 332:      * {@snippet :
> 333:      * offset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)

not 100% sold on this being a snippet. Looking at it with javadoc, we have the "copy" button - but this is not a piece of code in any way (at the very least the language should not be java)

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java line 383:

> 381:      * <p>The final offset returned by the method handle is computed as follows:
> 382:      *
> 383:      * {@snippet :

Same here - this is not a Java snippet

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java line 416:

> 414:      *
> 415:      * {@snippet :
> 416:      * address = base + offset

Same here - not a Java snippet

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java line 424:

> 422:      *
> 423:      * {@snippet :
> 424:      * offset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)

Same here - not a Java snippet

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java line 461:

> 459:      *
> 460:      * {@snippet :
> 461:      * bitOffset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)

Same here - not a Java snippet

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java line 602:

> 600:          * formula:
> 601:          * {@snippet :
> 602:          * E * (S + I * F)

Same here - not a Java snippet

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java line 152:

> 150:  *
> 151:  * {@snippet :
> 152:  * ...

I think we can drop the leading `...` here (since we're looking at this)

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

PR: https://git.openjdk.java.net/panama-foreign/pull/621