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

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

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

Commit messages:
 - Fix redundant import due to merge
 - Tweak package level javadoc
 - Merge branch 'foreign-preview' into null_javadoc
 - Polish javadoc

Changes: https://git.openjdk.java.net/panama-foreign/pull/669/files
 Webrev: https://webrevs.openjdk.java.net/?repo=panama-foreign&pr=669&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8283042
  Stats: 267 lines in 16 files changed: 50 ins; 52 del; 165 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