[foreign-preview] RFR: More javadoc cleanup.

[Paul Sandoz]

On Mon, 14 Mar 2022 19:30:17 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.

src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 67:

> 65:  * buffer memory segments might be backed by either off-heap memory or on-heap memory, depending on the characteristics of the
> 66:  * wrapped byte buffer instance. For instance, a buffer memory segment obtained from a byte buffer created with the
> 67:  * {@link ByteBuffer#allocateDirect(int)} method will be backed by off-heap memory.

Missing `</li>`

src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 226:

> 224:  * the memory segment.
> 225:  * <p>
> 226:  * For instance, clients requiring sophisticated, low-level control over mapped memory segments, might consider writing

Suggestion:

 * Clients requiring sophisticated, low-level control over mapped memory segments, might consider writing

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

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