[foreign-preview] Integrated: 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.

This pull request has now been integrated.

Changeset: 5e6e1576
Author:    Maurizio Cimadamore <mcimadamore at openjdk.org>
URL:       https://git.openjdk.java.net/panama-foreign/commit/5e6e157693aad143232d8bf63642a05165f2bb9e
Stats:     356 lines in 16 files changed: 49 ins; 52 del; 255 mod

8283042: Polish java.lang.foreign javadoc

Reviewed-by: jboes

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

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