RFR: 8353197: Document preconditions for JavaLangAccess methods [v5]

[Roger Riggs]

On Mon, 12 May 2025 10:17:46 GMT, Volkan Yazici <vyazici at openjdk.org> wrote:

>> Document preconditions on certain `JavaLangAccess` methods that use operations either unsafe and/or without range checks.
>
> Volkan Yazici has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Prefixed `JavaLangAccess::stringConcat1` with `unchecked`
>  - Fix `HexDigits` copyright year

src/java.base/share/classes/jdk/internal/access/JavaLangAccess.java line 328:

> 326:      * {@linkplain java.nio.charset.Charset charset}.
> 327:      * <p>
> 328:      * <b>WARNING: This method return the {@code byte[]} backing the provided

Suggestion:

     * <b>WARNING: This method returns the {@code byte[]} backing the provided

Should this more explicitly say the returned byte array must not be modified?

src/java.base/share/classes/jdk/internal/access/JavaLangAccess.java line 413:

> 411: 
> 412:     /**
> 413:      * Encodes ASCII codepoints as possible from the source array into

Suggestion:

     * Encodes as many ASCII codepoints as possible from the source array into

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

PR Review Comment: https://git.openjdk.org/jdk/pull/24982#discussion_r2085106836
PR Review Comment: https://git.openjdk.org/jdk/pull/24982#discussion_r2085112564