The javadoc of the java.lang.foreign package has several inconsistencies:

* not all the classes say what should happen when a `null` is passed; similarly what is done in other APIs, we should list the null-hostile behavior higher-up, in the package level javadoc.

* the notes for value-based and thread-safe are not always consistent.

* Method javadoc uses a mixture of third person and infinitive form.

* Inconsistent use of "Creates" vs. "Returns" vs. "Obtains". Following some analysis in JDK code, "Creates" is the common option for indicating creation of something that didn't exist before. "Returns" is used in a number of occurrences, including withers. Whereas "Obtains" seems relatively uncommon in the JDK and should be replaced.

* The first sentence of many javadoc methods is too long, and lead to a polluted summary page.

* The javadoc for some methods (e.g. GroupLayout::equals) is not rendered correctly, due to an issue in javadoc.

* the "new" term is used in several places, not always appropriately (e.g. when we create a slice of a segment, we don't necessarily return a "new" segment)