RFR (15) 8248011: Improve javadoc of Foreign Memory Access API

[Maurizio Cimadamore]

On 22/06/2020 19:22, Paul Sandoz wrote:
> Looks good, some very minor comment (no need for another round).
>
> MemoryLayout.java
> —
>
>   146  * That is, the above declaration is identical to the following, more verbose one:
>   147  * <blockquote><pre>{@code
>   148 MemoryLayout taggedValuesWithHole = MemoryLayout.ofSequence(5,
>   149     MemoryLayout.ofStruct(
>   150         MemoryLayout.ofPaddingBits(8, ByteOrder.NATIVE_ORDER).withName("kind").
>   151         MemoryLayout.ofPaddingBits(32),
>   152         MemoryLayout.ofPaddingBits(32)
>   153 ));
>
>
> Line 150 should be the following?
>
>    MemoryLayout.ofValueBits(8, ByteOrder.NATIVE_ORDER).withName("kind"),
Whoops yes
>
>
> MemorySegment.java
> —
>
>   156  * <blockquote><pre>{@code
>   157 MemorySegment segment = ...
>   158 SequenceLayout SEQUENCE_LAYOUT = MemoryLayout.ofSequence(1024, MemoryLayouts.JAVA_INT);
>   159 VarHandle VH_int = SEQUENCE_LAYOUT.elementLayout().varHandle(int.class);
>   160 int sum = StreamSupport.stream(MemorySegment.spliterator(segment, SEQUENCE_LAYOUT), true)
>   161 .mapToInt(s -> (int)VH_int.get(s.baseAddress()))
>   162 .sum();
>   163  * }</pre></blockquote>
>
> Indent lines 161 and 162?
ok
>
>
> package-info.java
> —
>
>    41  * <pre>{@code
>    42 static final VarHandle intHandle = MemoryHandles.varHandle(int.class, ByteOrder.nativeOrder());
>    43
>    44 try (MemorySegment segment = MemorySegment.allocateNative(10 * 4)) {
>    45    MemoryAddress base = segment.baseAddress();
>    46    for (long i = 0 ; i < 10 ; i++) {
>    47      intHandle.set(base.addOffset(i * 4), (int)i);
>    48    }
>    49  }
>    50  * }</pre>
>
> Alignment of ‘}’ in line 49 off by 1 space (too many).

I'll fix that

Thanks

Maurizio

>
> Paul.
>    
>
>> On Jun 22, 2020, at 7:41 AM, Maurizio Cimadamore <maurizio.cimadamore at oracle.com> wrote:
>>
>> Hi,
>> this is a patch fix address several javadoc issues in the foreign memory API, following some internal reviews (mostly from Brian, thanks!).
>>
>> The changes are aimed at reordering sections in the doc so that more advanced concepts are exposed last, and also to fix various issues in code samples (especially around MemoryLayout).
>>
>> Since I was there I also took the opportunity of dropping a now-unused method in MemoryAddressImpl (copy).
>>
>> Webrev:
>> http://cr.openjdk.java.net/~mcimadamore/8248011/
>>
>> Cheers
>> Maurizio
>>
>>