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

[Maurizio Cimadamore]

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

Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:

  Address review comments

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

Changes:
  - all: https://git.openjdk.java.net/panama-foreign/pull/669/files
  - new: https://git.openjdk.java.net/panama-foreign/pull/669/files/f31c9483..814dda9e

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=panama-foreign&pr=669&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=panama-foreign&pr=669&range=00-01

  Stats: 163 lines in 11 files changed: 0 ins; 1 del; 162 mod
  Patch: https://git.openjdk.java.net/panama-foreign/pull/669.diff
  Fetch: git fetch https://git.openjdk.java.net/panama-foreign pull/669/head:pull/669

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