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

[Paul Sandoz]

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"),


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?


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).

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
> 
>