[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.

src/java.base/share/classes/java/lang/foreign/CLinker.java line 161:

> 159: 
> 160:     /**
> 161:      * Creates a method handle which can be used to call a target foreign function with given signature and address.

with **the** given signature

src/java.base/share/classes/java/lang/foreign/CLinker.java line 184:

> 182: 
> 183:     /**
> 184:      * Creates a method handle which can be used to call a target foreign function with given signature.

same, "with **the** given signature"

src/java.base/share/classes/java/lang/foreign/CLinker.java line 204:

> 202: 
> 203:     /**
> 204:      * Creates a native stub which can be passed to other foreign functions as a function pointer, with given

with **the** given memory session

src/java.base/share/classes/java/lang/foreign/CLinker.java line 230:

> 228: 
> 229:     /**
> 230:      * {@return the downcall method handle {@linkplain MethodType type} associated with a given function descriptor}

with **the** given function descriptor

src/java.base/share/classes/java/lang/foreign/CLinker.java line 240:

> 238: 
> 239:     /**
> 240:      * {@return the method handle {@linkplain MethodType type} associated with an upcall stub with given function descriptor}

with **the** given function descriptor

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

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