RFR: 8345292: Improve javadocs for MemorySegment::getStrings defining word boundary cases [v6]

[Maurizio Cimadamore]

On Tue, 5 Aug 2025 11:31:48 GMT, Per Minborg <pminborg at openjdk.org> wrote:

>> This PR proposes to improve the 'MemorySegment.getString(long offset, Charset charset)` method documentation with respect to multi-octet concerns.
>
> Per Minborg has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains eight additional commits since the last revision:
> 
>  - Add a top-level section on string conversion
>  - Merge branch 'master' into ms-getstrings-boundary-doc
>  - Remove imp note
>  - Add text on N octets
>  - Improve wording
>  - Update src/java.base/share/classes/java/lang/foreign/MemorySegment.java
>    
>    Co-authored-by: Jorn Vernee <JornVernee at users.noreply.github.com>
>  - Update after comments
>  - Add info for multi-octet Charsets

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

> 408:  * boolean isAligned = segment.maxByteAlignment() >= layout.byteAlignment();
> 409:  * }
> 410:  * <h2 id="string-conversion">String conversion</h2>

I'd experiment adding this at the end of the section "Accessing memory segments" -- since this is really about memory segment access.

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

> 1323:      * @param charset the charset used to {@linkplain Charset#newDecoder() decode} the
> 1324:      *                string bytes. The {@code charset} must be a
> 1325:      *                {@linkplain StandardCharsets standard charset} as described

I believe `allocateFrom` in SegmentAllocator can benefit from a similar treatment?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25715#discussion_r2276229622
PR Review Comment: https://git.openjdk.org/jdk/pull/25715#discussion_r2276230458