[foreign-preview] RFR: 8283042: Polish java.lang.foreign javadoc

[Julia Boes]

On Fri, 11 Mar 2022 15:16:48 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This patch addresses the javadoc inconsistencies mentioned in JDK-8283042.
> 
> Here's a summary of the changes:
> 
> * treatment for `nulls` has been moved to toplevel javadoc
> * third person has been chosen over infinitive form in all method javadoc (this seems to be the most common form in JDK code, after some grepping)
> * `Creates` has been used in all places where a "new" object is returned;
> * `Returns` has been used in all places where a view of an object is returned
> * dropped `new` in all places where it could be over-constraining or misleading; I've also dropped `new` immediately after a `Creates`
> * Replaces most instances of `Obtains` with either `Creates` or `Returns` (which seems way more common, after some grepping)
> * Made javadoc for *wither* methods in `MemoryLayout` and `FunctionDescriptor` more uniform
> * Fix issue where layout subclasses did not inherit `MemoryLayout` javadoc for Object methods (due to javadoc issue)
> * Make sure that first sentence of all method javadoc is short and descriptive, and looks good in the class summary javadoc
> * Slightly tweaked the first sentence of the top-level package javadoc (to make sure it looks good in the java.base summary
> * Other minor fixes, mainly aimed to reduce some of the verbosity.

Only some minor comments on wording and punctuation.

src/java.base/share/classes/java/lang/foreign/MemoryAddress.java line 31:

> 29: import java.nio.ByteOrder;
> 30: 
> 31: import jdk.internal.ValueBased;

Is this an unused import?

src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 874:

> 872:     /**
> 873:      * Creates a native memory segment with given layout and memory session.
> 874:      * A client is responsible make sure that the memory session associated with the returned segment is closed

is responsible **for** ensuring that

src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 898:

> 896:     /**
> 897:      * Creates a native memory segment with given size (in bytes) and memory session.
> 898:      * A client is responsible make sure that the memory session associated with the returned segment is closed

same, "is responsible **for** ensuring that"

src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 921:

> 919:     /**
> 920:      * Creates a native memory segment with given size (in bytes), alignment constraint (in bytes) and memory session.
> 921:      * A client is responsible make sure that the memory session associated with the returned segment is closed when the

same, "is responsible for ensuring that"

src/java.base/share/classes/java/lang/foreign/SequenceLayout.java line 98:

> 96: 
> 97:     /**
> 98:      * Returns a sequence layout with same element layout, alignment constraints and name as this sequence layout,

with **the** same element layout

src/java.base/share/classes/java/lang/foreign/ValueLayout.java line 61:

> 59:  *
> 60:  * @implSpec
> 61:  * This class and its subclasses are immutable and thread-safe and <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>.

immutable, thread-safe and

src/java.base/share/classes/java/lang/foreign/ValueLayout.java line 92:

> 90: 
> 91:     /**
> 92:      * Returns a value layout with same carrier, alignment constraints and name as this value layout,

with **the** same carrier, ...

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

Marked as reviewed by jboes (Committer).

PR: https://git.openjdk.java.net/panama-foreign/pull/669