RFR: 8308645: Javadoc of FFM API needs to be refreshed [v4]

[Maurizio Cimadamore]

On Thu, 1 Jun 2023 19:36:48 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Fix wrong link in layout well-formedness doc
>
> src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 938:
> 
>> 936:      * the properties of this segment. For instance, if this segment is a {@linkplain #isReadOnly() read-only segment},
>> 937:      * then the resulting buffer is also {@linkplain ByteBuffer#isReadOnly() read-only}. Additionally, if this is a native
>> 938:      * segment, the resulting buffer is a {@linkplain ByteBuffer#isDirect() direct buffer}.
> 
> (Pre-existing, but seemed useful to mention) Rather than giving a few examples with 'For instance', perhaps this should more explicitly list _all_ the properties that are reflected in the returned buffer (not sure if there are more).

Good idea - it is not trivial to capture all the properties in a single para.

> src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java line 388:
> 
>> 386:      * knows that they have fully processed the contents of the allocated segment before the subsequent allocation request
>> 387:      * takes place.
>> 388:      * @implNote While a prefix allocator is <em>thread-safe</em>, concurrent access on the same recycling
> 
> Is the term "thread-safe" defined any where? Should it be?

I think the term is used pretty much all over the javadoc (not just FFM's) - e.g. look for this preamble:

 * <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>,
 * immutable and thread-safe
 ```

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14098#discussion_r1213670809
PR Review Comment: https://git.openjdk.org/jdk/pull/14098#discussion_r1213669418