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

[Maurizio Cimadamore]

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/AbstractLayout.java line 155:

> 153:     }
> 154: 
> 155:     /**

This, and other javadoc for Object methods has to be copied from `MemoryLayout` to here, or the javadoc rendering for the layout subclasses will just display the Object method javadoc.

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

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