Re: RFR: 8319324: FFM: Reformat javadocs [v2]
On Mon, 6 Nov 2023 08:08:34 GMT, Per Minborg 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 incremental webrev excludes the unrelated changes
> brought in by the merge/rebase. The pull request contains five additional
> commits since the last revision:
>
> - Merge master
> - Reformat javadocs
> - FFM: Harmonize the @throws tags in the javadocs
> - Merge branch 'master' into javadoc-throws
> - Harmonize some of the javadoc throws
src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 1910:
> 1908: * in the provided layout
> 1909: * @throws IndexOutOfBoundsException if {@code offset > byteSize()
> - layout.byteSize()}
> 1910: * @throws UnsupportedOperationException if this segment is
one `UOE` went missing
-
PR Review Comment: https://git.openjdk.org/jdk/pull/16518#discussion_r1382966088
Re: RFR: 8319324: FFM: Reformat javadocs [v2]
On Mon, 6 Nov 2023 08:08:34 GMT, Per Minborg 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 incremental webrev excludes the unrelated changes > brought in by the merge/rebase. The pull request contains five additional > commits since the last revision: > > - Merge master > - Reformat javadocs > - FFM: Harmonize the @throws tags in the javadocs > - Merge branch 'master' into javadoc-throws > - Harmonize some of the javadoc throws Generally looks good (I've been relying a lot on github diff annotations, so I hope those are accurate :-) ). There seem to be a couple of issues with deleted text. - PR Review: https://git.openjdk.org/jdk/pull/16518#pullrequestreview-1714576629
Re: RFR: 8319324: FFM: Reformat javadocs [v2]
On Mon, 6 Nov 2023 08:53:55 GMT, Maurizio Cimadamore wrote: >> Per Minborg has updated the pull request with a new target base due to a >> merge or a rebase. The incremental webrev excludes the unrelated changes >> brought in by the merge/rebase. The pull request contains five additional >> commits since the last revision: >> >> - Merge master >> - Reformat javadocs >> - FFM: Harmonize the @throws tags in the javadocs >> - Merge branch 'master' into javadoc-throws >> - Harmonize some of the javadoc throws > > src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 1630: > >> 1628: * Writes a boolean into this segment at the given offset, with >> the given layout. >> 1629: * >> 1630: * @param offset offset in bytes (relative to this segment >> address) at which this > > The first `@param` (layout) here has been deleted? Not just here - happened elsewhere too - PR Review Comment: https://git.openjdk.org/jdk/pull/16518#discussion_r1382956428
Re: RFR: 8319324: FFM: Reformat javadocs [v2]
On Mon, 6 Nov 2023 08:08:34 GMT, Per Minborg 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 incremental webrev excludes the unrelated changes > brought in by the merge/rebase. The pull request contains five additional > commits since the last revision: > > - Merge master > - Reformat javadocs > - FFM: Harmonize the @throws tags in the javadocs > - Merge branch 'master' into javadoc-throws > - Harmonize some of the javadoc throws src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 1630: > 1628: * Writes a boolean into this segment at the given offset, with the > given layout. > 1629: * > 1630: * @param offset offset in bytes (relative to this segment address) > at which this The first `@param` (layout) here has been deleted? - PR Review Comment: https://git.openjdk.org/jdk/pull/16518#discussion_r1382955037
Re: RFR: 8319324: FFM: Reformat javadocs [v2]
> 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 incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains five additional commits since the last revision: - Merge master - Reformat javadocs - FFM: Harmonize the @throws tags in the javadocs - Merge branch 'master' into javadoc-throws - Harmonize some of the javadoc throws - Changes: - all: https://git.openjdk.org/jdk/pull/16518/files - new: https://git.openjdk.org/jdk/pull/16518/files/5da69f89..d0fddb0f Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=16518=01 - incr: https://webrevs.openjdk.org/?repo=jdk=16518=00-01 Stats: 7264 lines in 172 files changed: 2735 ins; 2345 del; 2184 mod Patch: https://git.openjdk.org/jdk/pull/16518.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/16518/head:pull/16518 PR: https://git.openjdk.org/jdk/pull/16518
