RFR: 8332003: Clarify javadoc for MemoryLayout::offsetHandle [v2]

[Maurizio Cimadamore]

> Consider this layout:
> 
> 
> MemoryLayout SEQ = MemoryLayout.sequenceLayout(5,
>              MemoryLayout.sequenceLayout(10, JAVA_INT));
> 
> 
> And the corresponding offset handle:
> 
> 
> MethodHandle offsetHandle = SEQ.offsetHandle(PathElement.sequenceLayout(), PathElement.sequenceLayout());
> 
> 
> The resulting method handle takes two additional `long` indices. The implementation checks that the dynamically provided indices conform to the bound available at construction: that is, the first index must be < 5, while the second must be < 10. If this is not true, an `IndexOutOfBoundException` is thrown.
> 
> However, the javadoc for `MemoryLayout::byteOffsetHandle` doesn't claim anything in this direction. There are only some vague claims in the javadoc for `PathElement::sequenceElement()` and `PathElement::sequenceElement(long, long, long)` which make some claims on which indices are actually allowed, but the text seems more in the tone of a discussion, rather than actual normative text.
> 
> I've tweaked the javadoc for `MemoryLayout::byteOffsetHandle` to actually state that the indices will be checked against the "size" of the corresponding open path element (this is a new concept that I also have defined in the javadoc).
> 
> I also added a test for `byteOffsetHandle` as I don't think we had a test for that specifically (although this method is tested indirectly, via `MemoryLayout::varHandle`).

Maurizio Cimadamore has updated the pull request incrementally with two additional commits since the last revision:

 - Update copyright
 - Add javadoc to other MemoryLayout methods returning VarHandle/MethodHandle to describe which exception can be thrown by returned handle

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/19158/files
  - new: https://git.openjdk.org/jdk/pull/19158/files/7cfd222b..aa644d3d

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=19158&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=19158&range=00-01

  Stats: 37 lines in 2 files changed: 35 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/jdk/pull/19158.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/19158/head:pull/19158

PR: https://git.openjdk.org/jdk/pull/19158