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

[Paul Sandoz]

On Fri, 19 Jun 2020 14:56:13 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).
>
> Maurizio Cimadamore has updated the pull request with a new target base due to a merge or a rebase. The pull request
> now contains ten commits:
>  - Merge branch 'foreign-memaccess' into foreign-memaccess-doc2
>  - Merge branch 'foreign-memaccess-doc2' of https://github.com/mcimadamore/panama-foreign into foreign-memaccess-doc2
>  - Clarify MemoryLayout javadoc
>  - Update src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java
>    
>    Co-authored-by: Jorn Vernee <JornVernee at users.noreply.github.com>
>  - Update src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java
>    
>    Co-authored-by: Jorn Vernee <JornVernee at users.noreply.github.com>
>  - Merge branch 'foreign-memaccess' into foreign-memaccess-doc2
>  - Misc javadoc fixes
>  - Fix javadoc for close()
>  - Clarify javadoc w.r.t close and aliasing of existing memory sources.

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

> 53:  * a given memory location. Also, {@code intHandle} is stored in a {@code static} and {@code final} field, to
> achieve 54:  * better performances and allow for inlining of the memory access operation through the {@link
> java.lang.invoke.VarHandle} 55:  * instance. We then create a <em>native</em> memory segment, that is, a memory segment
> backed by

s/performances/performance

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

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