[foreign-memaccess+abi] RFR: 8291286: Improve JavaDocs for static constructors in MemorySession

[Maurizio Cimadamore]

On Thu, 28 Jul 2022 07:30:28 GMT, Per-Åke Minborg <duke at openjdk.org> wrote:

> This PR adds information to the static constructor methods in MemorySession to improve clarity for new users.
> 
> This is my first PR for a JDK project so I am eager to receive feedback and improvement suggestions from the community.

src/java.base/share/classes/java/lang/foreign/MemorySession.java line 231:

> 229: 
> 230:     /**
> 231:      * Creates and returns a new closeable, thread-confined memory session.

This `Creates and returns` is correct technically, but I can't find much evidence for it in the rest of the JDK. It gives 109 matches in current code base, whereas `Creates` has over 7K. I would leave this as is.

src/java.base/share/classes/java/lang/foreign/MemorySession.java line 235:

> 233:      * The returned memory session is confined to the current thread.
> 234:      * <p>
> 235:      * The returned memory session must eventually be closed to prevent memory leaks.

I suggest adding a linkplain on `closed` to point to the close method.

src/java.base/share/classes/java/lang/foreign/MemorySession.java line 295:

> 293:      * openShared(Cleaner.create()).asNonCloseable();
> 294:      * }
> 295:      * @return a non-closeable, thread-shared memory session, managed by a private {@link Cleaner} instance

not a big fan of thread-shared... maybe better expand the text a bit (e.g. `returns a non-closeable memory session that can be shared across threads, ...`)

src/java.base/share/classes/java/lang/foreign/MemorySession.java line 306:

> 304:      * The global memory session is non-closeable and can be shared across threads.
> 305:      * <p>
> 306:      * The global memory session is neither ever closed nor ever subject to cleaning.

These comments seem out of place, in the sense that the concept of memory session is defined in the top level javadoc. I'm not sure repeating what a global session is here adds much? If we really think that the old text is not good enough, then maybe pulling out the global session text into a subsection in the toplevel javadoc, and then referring to that one from here could be a better option (although, again, not sure this needs changing?).

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

PR: https://git.openjdk.org/panama-foreign/pull/693