[foreign-memaccess] Tweaks to JavaDoc

[Paul Sandoz]

FTR I updated the webrev with the patch below. I will push it soon. 

Paul.

diff -r cf9201c6d463 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java   Wed Nov 20 14:34:11 2019 -0800
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java   Wed Nov 20 16:45:16 2019 -0800
@@ -211,7 +211,7 @@
      * @apiNote if the layout path has one (or more) free dimensions,
      * the offset is computed as if all the indices corresponding to such dimensions were set to {@code 0}.
      *
-     * @param elements the layout paths.
+     * @param elements the layout path elements.
      * @return The offset of layout selected by a the layout path obtained by concatenating the path elements in {@code elements}.
      */
     default long offset(PathElement... elements) throws UnsupportedOperationException {
@@ -230,7 +230,7 @@
      * unspecified sequence access component contained in this layout path.
      *
      * @param carrier the var handle carrier type.
-     * @param elements the layout paths.
+     * @param elements the layout path elements.
      * @return a var handle which can be used to dereference memory at the layout denoted by given layout path.
      * @throws UnsupportedOperationException if the layout targeted by this path is not a {@link ValueLayout} layout.
      * @throws IllegalArgumentException if the carrier does not represent a primitive type, if the carrier is {@code void},
diff -r cf9201c6d463 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java    Wed Nov 20 14:34:11 2019 -0800
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java    Wed Nov 20 16:45:16 2019 -0800
@@ -36,7 +36,6 @@
 /**
  * A value layout. A value layout is used to model the memory layout associated with values of basic data types, such as <em>integral</em> types
  * (either signed or unsigned) and <em>floating-point</em> types. Each value layout has a size and a byte order (see {@link ByteOrder}).
- * When not explicitly provided, a value layout's byte order is assumed to be compatible with the platform byte order (see {@link ByteOrder#nativeOrder()}).
  *
  * <p>
  * This is a <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>
diff -r cf9201c6d463 src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java   Wed Nov 20 14:34:11 2019 -0800
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java   Wed Nov 20 16:45:16 2019 -0800
@@ -50,7 +50,7 @@
  * <p>
  * The key abstractions introduced by this package are {@link jdk.incubator.foreign.MemorySegment} and {@link jdk.incubator.foreign.MemoryAddress}.
  * The first models a contiguous memory region, which can reside either inside or outside the Java heap; the latter models an address - that is,
- * an offset inside a given segment. A Memory address represents the main access coordinate of a memory access var handle, which can be obtained
+ * an offset inside a given segment. A memory address represents the main access coordinate of a memory access var handle, which can be obtained
  * using the combinator methods defined in the {@link jdk.incubator.foreign.MemoryHandles} class. Finally, the {@link jdk.incubator.foreign.MemoryLayout} class
  * hierarchy enables description of <em>memory layouts</em> and basic operations such as computing the size in bytes of a given
  * layout, obtain its alignment requirements, and so on. Memory layouts also provide an alternate, more abstract way, to produce



> On Nov 20, 2019, at 3:16 PM, Maurizio Cimadamore <maurizio.cimadamore at oracle.com> wrote:
> 
> Many thanks for the thorough pass. Few questions:
> 
> --- MemoryLayout::varHandle
> 
> "* @param elements the layout paths."
> 
> While this is better than what was there before, I think it should be "the layout path elements" ?
> 
> --- MemorySegment, good catch on the 'close' toplevel doc - seems like it was leftover from the previous round.
> 
> -- ValueLayout
> 
> this sentence:
> 
> "+ * When not explicitly provided, a value layout's byte order is assumed to be compatible with the platform byte order (see {@link ByteOrder#nativeOrder()})."
> 
> I think should go away - we don't have implicit endianness anymore.
> 
> -- package-info
> 
> "A Memory address" -> "A memory address"
> 
> 
> Other than that, looks great - feel free to push (if you want, or I can do that too)
> 
> Maurizio
> 
> On 20/11/2019 22:34, Paul Sandoz wrote:
>> Hi,
>> 
>> Here are some suggested tweaks to the JavaDoc.
>> 
>> http://cr.openjdk.java.net/~psandoz/panama/foreign-memaccess-javadoc/webrev/ <http://cr.openjdk.java.net/~psandoz/panama/foreign-memaccess-javadoc/webrev/>
>> 
>> —
>> 
>> Some observations:
>> 
>> - IllegalArgumentException is used to indicate out of bounds exceptions rather than IndexOutOfBoundsException
>> 
>> - RuntimeException is occasionally used e.g. "specified size is too large for the system runtime"
>> 
>> - Layout classes state:
>> 
>> * @implSpec
>> * This class is immutable and thread-safe.
>> 
>> This seems to be more of a spec requirement than an implementation detail.
>> 
>> Paul.
>>