[foreign-preview] RFR: More javadoc cleanup. [v4]

[Julia Boes]

On Mon, 14 Mar 2022 22:27:42 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> I noticed more inconsistencies in the foreogn API javadoc. For instance, the text saying that a class is value-based was in some cases repeated twice, once inside the main javadoc, and another as an `@implSpec`. I've removed all duplicates, and opted for the `@implSpec` version, that is more succint and more separated from the main javadoc text.
>> 
>> I have also reworked the javadoc of `MemorySession` and `MemorySegment`. The `MemorySession` javadoc contained a big list of all the possible things that can be associated with a session and what happens to them once the session is closed. I found this to be redundant and I've decided to streamline the text a little.
>> 
>> As for `MemorySegment`, the javadoc has evolved into many different small subsections. I've consolidated the text, by quickly listing all types of memory segments at the top. I've also dropped the section on "views" (which is something that is far less important in this iteraton of the API) and created a new session on slicing, which covers both slices and stream support. The result makes, I think, a lot more sense.
>> 
>> Finally, I've tweaked some text in `SegmentAllocator` where we're still referring to `array` event though the signatures of the methods take a varargs.
>
> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Replace @link with @linkplain where appropriate

Looks good!

src/java.base/share/classes/java/lang/foreign/MemoryAddress.java line 52:

> 50:  * Each dereference method takes a {@linkplain ValueLayout value layout}, which specifies the size,
> 51:  * alignment constraints, byte order as well as the Java type associated with the dereference operation, and an offset.
> 52:  * For instance, to read an int from a segment, using {@linkplain ByteOrder#nativeOrder() default endianness}, the following code can be used:

Tiny nit: line 42 of MemoryAddress should end with semicolon, line 43 is missing `</li>`

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

Marked as reviewed by jboes (Committer).

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