RFR: 8319324: FFM: Reformat javadocs [v11]

[Maurizio Cimadamore]

On Thu, 9 Nov 2023 12:31:16 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 with a new target base due to a merge or a rebase. The pull request now contains 14 commits:
> 
>  - Merge branch 'master' into javadoc-reformat
>  - Merge master
>  - Update after additional reviews
>  - Remove additional redundant full stops
>  - Merge master and update Linker formatting
>  - Harmonize the use of full stops in tags
>  - Remove double spaces after full stops
>  - Review classes not in the foreign package
>  - Update after review
>  - Merge master
>  - ... and 4 more: https://git.openjdk.org/jdk/compare/dd9eab15...b3c4293b

src/java.base/share/classes/java/lang/foreign/Arena.java line 35:

> 33: /**
> 34:  * An arena controls the lifecycle of native memory segments, providing both flexible
> 35:  * allocation and timely de-allocation.

Please revert all uses of "de-allocation". I don't think that's incorrect - seems more of a pedantic check from the tool.

src/java.base/share/classes/java/lang/foreign/Linker.java line 878:

> 876:          /**
> 877:          * {@return a struct layout that represents the layout of the capture state
> 878:           *         segment that is passedto a downcall handle linked with

there's a mistake `passedto` w/o spaces

src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 491:

> 489:  * so that the size of the segment is the same as the size of the target layout . In other
> 490:  * words, the returned segment is no longer a zero-length memory segment, and the pointer
> 491:  * it represents can be de-referenced directly:

Please revert "de-referenced"

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16518#discussion_r1387948515
PR Review Comment: https://git.openjdk.org/jdk/pull/16518#discussion_r1387949177
PR Review Comment: https://git.openjdk.org/jdk/pull/16518#discussion_r1387952260