RFR: 8364317: Explicitly document some assumptions of StringUTF16 [v2]

[Chen Liang]

On Wed, 30 Jul 2025 14:15:57 GMT, Chen Liang <liach at openjdk.org> wrote:

>> A good initiative, thanks @liach.
>> Maybe some words about endianness would be useful as well.
>
> @rgiulietti: I have added a paragraph describing the layout constraints of UTF16 byte arrays. Please check it out.

> @liach, given the relatively big API surface of j.l.StringUTF16, are we certain about this?

I am. In fact, your update to use `char` made it less correct - there are a few APIs that take LATIN1 byte arrays, for which number of chars is equivalent to number of bytes.

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

PR Comment: https://git.openjdk.org/jdk/pull/26541#issuecomment-3140762852