RFR: 8329997: Add provisions for checking memory segment alignment constraints [v3]

[Maurizio Cimadamore]

On Mon, 15 Apr 2024 14:39:02 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> 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 ten additional commits since the last revision:
>> 
>>  - Update after comments
>>  - Merge branch 'master' into ms-reinterpret2
>>  - Update src/java.base/share/classes/jdk/internal/foreign/HeapMemorySegmentImpl.java
>>    
>>    Co-authored-by: Jorn Vernee <JornVernee at users.noreply.github.com>
>>  - Update src/java.base/share/classes/jdk/internal/foreign/NativeMemorySegmentImpl.java
>>    
>>    Co-authored-by: Jorn Vernee <JornVernee at users.noreply.github.com>
>>  - Update src/java.base/share/classes/java/lang/foreign/MemorySegment.java
>>    
>>    Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>>  - Fix imports and copyright
>>  - Update maxByteAlignment docs
>>  - Improve doc and tests
>>  - Add a MS::maxByteAlignment method
>
> src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 612:
> 
>> 610:      *     <li>Heap:
>> 611:             derived from the segment {@linkplain #address() address()}
>> 612:             and the type of the <a href="#segment-alignment">backing heap storage</a>.
> 
> Shoudn't the link point to `MemorySegment::heapObject` ?

I suggest you generate the javadoc and look at this method - my feeling is that it won't be very readable. The sentence "a power of two and is derived from" is left a bit suspended - and you have a bullet list which starts with "Native Segment" which is not a valid "next token" for the sentence above. After which, we say again "derived from" hence repeating.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/18779#discussion_r1565913273