There are some things that need to be improved in the javadoc of the foreign memory API:

* the javadoc for close() is not very clear that closing a segment is an operation that is local to the segment, and not to the underlying memory source being referenced

* some extra documentation might be added to clarify that external memory sources (arrays and bytebuffers) might be aliased with multiple segments.

* some reordering in package level javadoc/MemorySegment javadoc to allow for easier concepts to introduced before more complex ones