RFR: 8319324: FFM: Reformat javadocs [v8]

[Maurizio Cimadamore]

On Mon, 6 Nov 2023 17:35:31 GMT, Per Minborg <pminborg at openjdk.org> wrote:

>> This PR proposes to reformat all the JavaDocs for the FFM API. This would bring the FFM API docs more in line with the existing Java documentation (see below).  Occasional drive-by fixes are also included in this PR (such as spelling and capitalization).
>> 
>> I am aware this PR will (if approved) make a significant mark in the change logs which is regrettable.
>> 
>> Background:
>> 
>> Older classes like `Object` and `List` have a maximum line length of 80 characters whereas newer classes like `ScopedValue` have a maximum line length of 90 characters.
>> 
>> The FFM API currently has javadoc lines that exceed 135 characters per line. It is also customary to use double spaces when starting a new sentence.
>
> Per Minborg has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Remove additional redundant full stops

src/java.base/share/classes/java/lang/foreign/MemoryLayout.java line 510:

> 508:      *          the given alignment constraint (in bytes)}
> 509:      *
> 510:      * @param byteAlignment the layout alignment constraint, expressed in bytes.

period?

src/java.base/share/classes/java/lang/foreign/MemoryLayout.java line 848:

> 846: 
> 847:         /**
> 848:          * Returns a path element which selects a member layout with the given name in a

It feels like the javadoc of the methods in here can be tightened using `{@return}`. Maybe for another PR.

src/java.base/share/classes/java/lang/foreign/MemoryLayout.java line 1017:

> 1015:      * @param elementCount the sequence element count
> 1016:      * @param elementLayout the sequence element layout
> 1017:      * @return the new sequence layout with the given element layout and size.

period?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16518#discussion_r1383726736
PR Review Comment: https://git.openjdk.org/jdk/pull/16518#discussion_r1383728935
PR Review Comment: https://git.openjdk.org/jdk/pull/16518#discussion_r1383729384