[foreign-memaccess] RFR: 8247924: Improve javadoc of Foreign Memory Access API (part two)

[Jorn Vernee]

On Fri, 19 Jun 2020 12:53:46 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This patch addresses some misc issues in the foreign memory access javadoc, following some feedback from Brian
> (thanks!).
> Things to look out for:
> 
> * the package-level javadoc has been tweaked so that we first introduce the entities, then the example - also there's a
>   bit more text to make things clearer
> * the javadoc section in MemorySegment on confinement has been moved at the end - since it's fairly advanced
> * the toplevel javadoc of `MemoryLayout` has been reworked pretty substantially; it now has a leading example which shows
>   how to go from a C decl to a layout; that same example is then reused throughout the javadoc to explain layout paths
> 
> When doing this, I realized that the section on layout paths has several mistakes - from code mistakes to a section
> which was repeated twice (!!) no idea how that could have gone through all the review rounds (it's not a merge
> artifact - same issue is in jdk/jdk).

Marked as reviewed by jvernee (Committer).

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

> 127:  * For instance, given the {@code taggedValues} layout instance constructed as above, we can obtain the offset,
> 128:  * in bits, of the <em>first</em> member layout named <code>value</code>, as follows:
> 129:  * <blockquote><pre>{@code

Shouldn't it say 'the second member layout'? ('kind' is the first)

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

> 149:     MemoryLayout.ofStruct(
> 150:         MemoryLayout.ofPaddingBits(8, ByteOrder.NATIVE_ORDER).withName("tag").
> 151:         MemoryLayout.ofPaddingBits(32),

Suggestion:

        MemoryLayout.ofPaddingBits(8, ByteOrder.NATIVE_ORDER).withName("kind").

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

> 37:  *
> 38:  * For example, to allocate an off-heap memory region big enough to hold 10 values of the primitive type {@code
> int}, and fill it values 39:  * ranging from {@code 0} to {@code 9}, we can use the following code:

Suggestion:

 * For example, to allocate an off-heap memory region big enough to hold 10 values of the primitive type {@code int}, and
   fill it with values

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

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