RFR: 8308281: Java snippets in the FFM API need to be updated

[Chen Liang]

On Wed, 17 May 2023 11:46:39 GMT, Per Minborg <pminborg at openjdk.org> wrote:

> As the API has improved over the recent releases, not all `{@snippet ..}` sections have been kept in sync.
> 
> This PR suggests all snippets used should be verified against real code that is placed in a new `snippet-files` folder and erroneous snippets are updated.
> 
> In this PR, it is suggested duplicating code in the `Snippets.java` class and in the JavaDocs. The benefit of this is that code is directly visible in the code and not only in the generated javadoc.
> 
> Another thing to think about is if there should be on single `Snippets.java` class or separate ones for each FFM class.

src/java.base/share/classes/java/lang/foreign/Arena.java line 168:

> 166:  *
> 167:  *      public MemorySegment allocate(long byteSize, long byteAlignment) {
> 168:  *            return slicingAllocator.allocate(byteSize, byteAlignment);

Shouldn't the indentation be 4 spaces?
Suggestion:

 *          return slicingAllocator.allocate(byteSize, byteAlignment);

src/java.base/share/classes/java/lang/foreign/Arena.java line 172:

> 170:  *
> 171:  *      public MemorySegment.Scope scope() {
> 172:  *            return arena.scope();

Suggestion:

 *          return arena.scope();

src/java.base/share/classes/java/lang/foreign/Arena.java line 176:

> 174:  *
> 175:  *      public void close() {
> 176:  *            arena.close();

Suggestion:

 *          arena.close();

src/java.base/share/classes/java/lang/foreign/Linker.java line 96:

> 94:  * try (Arena arena = Arena.ofConfined()) {
> 95:  *     MemorySegment str = arena.allocateUtf8String("Hello");
> 96:  *     long len          = (long) strlen.invoke(str);  // 5

Suggestion:

 *     long len          = (long) strlen.invokeExact(str);  // 5

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14030#discussion_r1196588335
PR Review Comment: https://git.openjdk.org/jdk/pull/14030#discussion_r1196588479
PR Review Comment: https://git.openjdk.org/jdk/pull/14030#discussion_r1196588748
PR Review Comment: https://git.openjdk.org/jdk/pull/14030#discussion_r1196593902