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

[Maurizio Cimadamore]

On Tue, 10 Jun 2025 09:01:17 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.

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

> 1299:      * <p>
> 1300:      * If the {@linkplain #byteSize()} of this segment is not evenly dividable by the
> 1301:      * number of octets used by provided {@code charset}, the reminding bytes of this

`the remaining bytes of this segment are not accessed`

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

> 1300:      * If the {@linkplain #byteSize()} of this segment is not evenly dividable by the
> 1301:      * number of octets used by provided {@code charset}, the reminding bytes of this
> 1302:      * segment is not accessed. For multi-octet charset, nulls are only detected on

Elsewhere in the javadoc we say string terminator/terminator char. The mention of `null` is surprising here.

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

> 1301:      * number of octets used by provided {@code charset}, the reminding bytes of this
> 1302:      * segment is not accessed. For multi-octet charset, nulls are only detected on
> 1303:      * multi-octet-aligned boundaries.

This feels like an implementation note rather that something that belongs to the javadoc?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/25715#discussion_r2138255612
PR Review Comment: https://git.openjdk.org/jdk/pull/25715#discussion_r2138258190
PR Review Comment: https://git.openjdk.org/jdk/pull/25715#discussion_r2138259170