Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base` [v2]
On Fri, 19 Apr 2024 19:21:13 GMT, Jonathan Gibbons wrote: >> Please review a set of updates to clean up use of `/**` comments in the >> vicinity of declarations. >> >> There are various categories of update: >> >> * "Box comments" beginning with `/**` >> * Misplaced doc comments before package or import statements >> * Misplaced doc comments after the annotations for a declaration >> * Dangling `/**` comments relating to a group of declarations, separate from >> the doc comments for each of those declarations >> * Use of `/**` for the legal header at or near the top of the file >> >> In one case, two doc comments before a declaration were merged, which fixes >> a bug/omission in the documented serialized form. > > Jonathan Gibbons has updated the pull request incrementally with one > additional commit since the last revision: > > Update > src/java.base/share/classes/sun/net/www/protocol/file/FileURLConnection.java > > Fix grammatical typo > > Co-authored-by: Alexey Ivanov Marked as reviewed by iris (Reviewer). - PR Review: https://git.openjdk.org/jdk/pull/18846#pullrequestreview-2016126206
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base` [v2]
On Fri, 19 Apr 2024 19:21:13 GMT, Jonathan Gibbons wrote: >> Please review a set of updates to clean up use of `/**` comments in the >> vicinity of declarations. >> >> There are various categories of update: >> >> * "Box comments" beginning with `/**` >> * Misplaced doc comments before package or import statements >> * Misplaced doc comments after the annotations for a declaration >> * Dangling `/**` comments relating to a group of declarations, separate from >> the doc comments for each of those declarations >> * Use of `/**` for the legal header at or near the top of the file >> >> In one case, two doc comments before a declaration were merged, which fixes >> a bug/omission in the documented serialized form. > > Jonathan Gibbons has updated the pull request incrementally with one > additional commit since the last revision: > > Update > src/java.base/share/classes/sun/net/www/protocol/file/FileURLConnection.java > > Fix grammatical typo > > Co-authored-by: Alexey Ivanov Marked as reviewed by darcy (Reviewer). - PR Review: https://git.openjdk.org/jdk/pull/18846#pullrequestreview-2016121831
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base`
On Mon, 22 Apr 2024 17:38:59 GMT, Jonathan Gibbons wrote: > The document [How to Write Doc Comments for the Javadoc > Tool](https://www.oracle.com/uk/technical-resources/articles/java/javadoc-tool.html) > is depressingly obsolete, as indicated by this text towards the end: I know. Yet there's nothing newer, is there? - PR Comment: https://git.openjdk.org/jdk/pull/18846#issuecomment-2070433346
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base`
On Fri, 19 Apr 2024 19:29:31 GMT, Alexey Ivanov wrote: > > We do not have an overall style guide. The conventional wisdom for editing > > any existing file is to follow the style in that file, if such a style can > > be discerned. > > That's what I do. > > I saw either style used in JDK. Yet I didn't check which style is more > common… to decide which style I should use when creating new files with > javadoc comments. [How to Write Doc Comments for the Javadoc > Tool](https://www.oracle.com/uk/technical-resources/articles/java/javadoc-tool.html) > doesn't have a blank line between the javadoc comment and class declaration; > nor do javadoc comments for fields and methods. The document [How to Write Doc Comments for the Javadoc Tool](https://www.oracle.com/uk/technical-resources/articles/java/javadoc-tool.html) is depressingly obsolete, as indicated by this text towards the end: >Footnotes > > [1] At Java Software, we use @version for the SCCS version. See "man > sccs-get" for details. The consensus seems to be the following: - PR Comment: https://git.openjdk.org/jdk/pull/18846#issuecomment-2070379608
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base` [v2]
On Fri, 19 Apr 2024 20:38:05 GMT, Naoto Sato wrote: > OK, fair enough. Approving for the `icu` part Thank you. - PR Comment: https://git.openjdk.org/jdk/pull/18846#issuecomment-2067280359
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base` [v2]
On Fri, 19 Apr 2024 19:21:13 GMT, Jonathan Gibbons wrote: >> Please review a set of updates to clean up use of `/**` comments in the >> vicinity of declarations. >> >> There are various categories of update: >> >> * "Box comments" beginning with `/**` >> * Misplaced doc comments before package or import statements >> * Misplaced doc comments after the annotations for a declaration >> * Dangling `/**` comments relating to a group of declarations, separate from >> the doc comments for each of those declarations >> * Use of `/**` for the legal header at or near the top of the file >> >> In one case, two doc comments before a declaration were merged, which fixes >> a bug/omission in the documented serialized form. > > Jonathan Gibbons has updated the pull request incrementally with one > additional commit since the last revision: > > Update > src/java.base/share/classes/sun/net/www/protocol/file/FileURLConnection.java > > Fix grammatical typo > > Co-authored-by: Alexey Ivanov OK, fair enough. Approving for the `icu` part - Marked as reviewed by naoto (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/18846#pullrequestreview-2012372872
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base` [v2]
On Fri, 19 Apr 2024 19:47:20 GMT, Naoto Sato wrote: > Unless it is absolutely necessary, I would not fix comments in > `jdk.internal.icu` sources, as they are in the upstream code, and would like > to minimize the merging effort. @naotoj Given the policy and strong desire to compile `java.base` with all lint warnings enabled and `-Werror`, all of the proposed changes in this PR will each individually break the build if/when the warning is added to `javac` and we continue to compile `java.base` with the current build settings. - PR Comment: https://git.openjdk.org/jdk/pull/18846#issuecomment-2067246948
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base` [v2]
On Fri, 19 Apr 2024 19:21:13 GMT, Jonathan Gibbons wrote: >> Please review a set of updates to clean up use of `/**` comments in the >> vicinity of declarations. >> >> There are various categories of update: >> >> * "Box comments" beginning with `/**` >> * Misplaced doc comments before package or import statements >> * Misplaced doc comments after the annotations for a declaration >> * Dangling `/**` comments relating to a group of declarations, separate from >> the doc comments for each of those declarations >> * Use of `/**` for the legal header at or near the top of the file >> >> In one case, two doc comments before a declaration were merged, which fixes >> a bug/omission in the documented serialized form. > > Jonathan Gibbons has updated the pull request incrementally with one > additional commit since the last revision: > > Update > src/java.base/share/classes/sun/net/www/protocol/file/FileURLConnection.java > > Fix grammatical typo > > Co-authored-by: Alexey Ivanov Unless it is absolutely necessary, I would not fix comments in `jdk.internal.icu` sources, as they are in the upstream code, and would like to minimize the merging effort. - PR Comment: https://git.openjdk.org/jdk/pull/18846#issuecomment-2067190364
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base`
On Fri, 19 Apr 2024 19:18:31 GMT, Jonathan Gibbons wrote: > We do not have an overall style guide. The conventional wisdom for editing > any existing file is to follow the style in that file, if such a style can be > discerned. That's what I do. I saw either style used in JDK. Yet I didn't check which style is more common… to decide which style I should use when creating new files with javadoc comments. [How to Write Doc Comments for the Javadoc Tool](https://www.oracle.com/uk/technical-resources/articles/java/javadoc-tool.html) doesn't have a blank line between the javadoc comment and class declaration; nor do javadoc comments for fields and methods. - PR Comment: https://git.openjdk.org/jdk/pull/18846#issuecomment-2067169319
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base` [v2]
On Fri, 19 Apr 2024 19:21:13 GMT, Jonathan Gibbons wrote: >> Please review a set of updates to clean up use of `/**` comments in the >> vicinity of declarations. >> >> There are various categories of update: >> >> * "Box comments" beginning with `/**` >> * Misplaced doc comments before package or import statements >> * Misplaced doc comments after the annotations for a declaration >> * Dangling `/**` comments relating to a group of declarations, separate from >> the doc comments for each of those declarations >> * Use of `/**` for the legal header at or near the top of the file >> >> In one case, two doc comments before a declaration were merged, which fixes >> a bug/omission in the documented serialized form. > > Jonathan Gibbons has updated the pull request incrementally with one > additional commit since the last revision: > > Update > src/java.base/share/classes/sun/net/www/protocol/file/FileURLConnection.java > > Fix grammatical typo > > Co-authored-by: Alexey Ivanov Marked as reviewed by aivanov (Reviewer). - PR Review: https://git.openjdk.org/jdk/pull/18846#pullrequestreview-2012219677
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base`
On Fri, 19 Apr 2024 11:32:55 GMT, Pavel Rappo wrote: > This comment is not a review. I simply use the opportunity provided by this > PR to suggest that we stop making new `/** ... */` and separately fix old > jtreg comments like this: > > ``` > /** > * @test TestSmallHeap > * @bug 8067438 8152239 > * @summary Verify that starting the VM with a small heap works > * @library /test/lib > * @modules java.base/jdk.internal.misc > * @build jdk.test.whitebox.WhiteBox > * @run driver jdk.test.lib.helpers.ClassFileInstaller > jdk.test.whitebox.WhiteBox > * @run main/othervm -Xbootclasspath/a:. -XX:+UnlockDiagnosticVMOptions > -XX:+WhiteBoxAPI gc.TestSmallHeap > */ > ``` > > I know that those comments only appear in tests, and that tests are never > documented. Still, it is confusing to see such comments and IDEs might frown > upon them too. Generally, it is a good rule of thumb that `/** ... */` should > be reserved only for javadoc. I agree we should not be using `/**` for test description comments. IntelliJ tells me there are 103+ matches in 97+ files, so this would be a non-trivial cleanup. I note there are 22 issues in `test/langtools/jdk` tests (i.e. javadoc tests), so let's start there ;-) - PR Comment: https://git.openjdk.org/jdk/pull/18846#issuecomment-2067164929
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base` [v2]
> Please review a set of updates to clean up use of `/**` comments in the > vicinity of declarations. > > There are various categories of update: > > * "Box comments" beginning with `/**` > * Misplaced doc comments before package or import statements > * Misplaced doc comments after the annotations for a declaration > * Dangling `/**` comments relating to a group of declarations, separate from > the doc comments for each of those declarations > * Use of `/**` for the legal header at or near the top of the file > > In one case, two doc comments before a declaration were merged, which fixes a > bug/omission in the documented serialized form. Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: Update src/java.base/share/classes/sun/net/www/protocol/file/FileURLConnection.java Fix grammatical typo Co-authored-by: Alexey Ivanov - Changes: - all: https://git.openjdk.org/jdk/pull/18846/files - new: https://git.openjdk.org/jdk/pull/18846/files/fcbe02d5..d7b46a85 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk=18846=01 - incr: https://webrevs.openjdk.org/?repo=jdk=18846=00-01 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.org/jdk/pull/18846.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/18846/head:pull/18846 PR: https://git.openjdk.org/jdk/pull/18846
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base` [v2]
On Fri, 19 Apr 2024 10:49:11 GMT, Alexey Ivanov wrote: >> Jonathan Gibbons has updated the pull request incrementally with one >> additional commit since the last revision: >> >> Update >> src/java.base/share/classes/sun/net/www/protocol/file/FileURLConnection.java >> >> Fix grammatical typo >> >> Co-authored-by: Alexey Ivanov > > src/java.base/share/classes/sun/net/www/protocol/file/FileURLConnection.java > line 38: > >> 36: >> 37: /** >> 38: * Open an file input stream given a URL. > > Suggestion: > > * Open a file input stream given a URL. OK, I'll accept this as a minor typo mixup, that does not in itself need a CSR. But generally, it is not a goal to fix issues in the content of doc comments. - PR Review Comment: https://git.openjdk.org/jdk/pull/18846#discussion_r1572821973
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base`
On Thu, 18 Apr 2024 20:44:00 GMT, Jonathan Gibbons wrote:
> Please review a set of updates to clean up use of `/**` comments in the
> vicinity of declarations.
>
> There are various categories of update:
>
> * "Box comments" beginning with `/**`
> * Misplaced doc comments before package or import statements
> * Misplaced doc comments after the annotations for a declaration
> * Dangling `/**` comments relating to a group of declarations, separate from
> the doc comments for each of those declarations
> * Use of `/**` for the legal header at or near the top of the file
>
> In one case, two doc comments before a declaration were merged, which fixes a
> bug/omission in the documented serialized form.
> It is somewhat off-topic. Yet I noticed javadoc comments in some files are
> followed a blank line, and others aren't. Out of my curiosity, is there a
> convention about the blank line between the javadoc comment and the class or
> interface declaration? Should there be one?
>
> ```java
> /**
> * This is a class.
> */
> public class A {}
> ```
>
> or
>
> ```java
> /**
> * This is a class.
> */
>
> public class A {}
> ```
>
> Which is the most common? Which is preferred?
We do not have an overall style guide. The conventional wisdom for editing
any existing file is to follow the style in that file, if such a style can be
discerned.
-
PR Comment: https://git.openjdk.org/jdk/pull/18846#issuecomment-2067156407
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base`
On Fri, 19 Apr 2024 10:44:27 GMT, Alexey Ivanov wrote: >> Please review a set of updates to clean up use of `/**` comments in the >> vicinity of declarations. >> >> There are various categories of update: >> >> * "Box comments" beginning with `/**` >> * Misplaced doc comments before package or import statements >> * Misplaced doc comments after the annotations for a declaration >> * Dangling `/**` comments relating to a group of declarations, separate from >> the doc comments for each of those declarations >> * Use of `/**` for the legal header at or near the top of the file >> >> In one case, two doc comments before a declaration were merged, which fixes >> a bug/omission in the documented serialized form. > > src/java.base/share/classes/com/sun/crypto/provider/SunJCE.java line 37: > >> 35: import static sun.security.util.SecurityProviderConstants.*; >> 36: >> 37: /* > > Should this be included in the main javadoc comment? The `@author` tags > belong in the javadoc comment. > > The javadoc itself is likely unreadable, when processed the entire comment > becomes one very long paragraph. That would be up to the relevant component to decide how to improve these comments. The goal here is proactively fix any warnings that may be generated about multiple doc comments on a declaration. I note that neither comment contributes to the public API, and that `@author` tags are generally obsolete these days. The VCS metadata is a more accurate reflection of individual contributions. - PR Review Comment: https://git.openjdk.org/jdk/pull/18846#discussion_r1572818078
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base`
On Fri, 19 Apr 2024 10:53:11 GMT, Alexey Ivanov wrote:
>> Please review a set of updates to clean up use of `/**` comments in the
>> vicinity of declarations.
>>
>> There are various categories of update:
>>
>> * "Box comments" beginning with `/**`
>> * Misplaced doc comments before package or import statements
>> * Misplaced doc comments after the annotations for a declaration
>> * Dangling `/**` comments relating to a group of declarations, separate from
>> the doc comments for each of those declarations
>> * Use of `/**` for the legal header at or near the top of the file
>>
>> In one case, two doc comments before a declaration were merged, which fixes
>> a bug/omission in the documented serialized form.
>
> src/java.base/macosx/classes/apple/security/AppleProvider.java line 33:
>
>> 31: /*
>> 32: * The Apple Security Provider.
>> 33: */
>
> Does it make sense to incorporate this comment into the following javadoc
> comment?
>
>
> /**
> * Defines the (an) Apple security provider.
> * ...
> */
> @SuppressWarnings("serial") // JDK implementation class
Maybe, but only maybe, and if so, it would be out of scope for this work. That
would be up to the relevant component team.
That being said, neither comment is part of any public API, and this comment is
effectively already present in the first sentence of the actual doc comment.
-
PR Review Comment: https://git.openjdk.org/jdk/pull/18846#discussion_r1572813320
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base`
On Thu, 18 Apr 2024 20:44:00 GMT, Jonathan Gibbons wrote: > Please review a set of updates to clean up use of `/**` comments in the > vicinity of declarations. > > There are various categories of update: > > * "Box comments" beginning with `/**` > * Misplaced doc comments before package or import statements > * Misplaced doc comments after the annotations for a declaration > * Dangling `/**` comments relating to a group of declarations, separate from > the doc comments for each of those declarations > * Use of `/**` for the legal header at or near the top of the file > > In one case, two doc comments before a declaration were merged, which fixes a > bug/omission in the documented serialized form. This comment is not a review. I simply use the opportunity provided by this PR to suggest that we stop making new `/** ... */` and separately fix old jtreg comments like this: /** * @test TestSmallHeap * @bug 8067438 8152239 * @summary Verify that starting the VM with a small heap works * @library /test/lib * @modules java.base/jdk.internal.misc * @build jdk.test.whitebox.WhiteBox * @run driver jdk.test.lib.helpers.ClassFileInstaller jdk.test.whitebox.WhiteBox * @run main/othervm -Xbootclasspath/a:. -XX:+UnlockDiagnosticVMOptions -XX:+WhiteBoxAPI gc.TestSmallHeap */ I know that those comments only appear in tests, and that tests are never documented. Still, it is confusing to see such comments and IDEs might frown upon them too. Generally, it is a good rule of thumb that `/** ... */` should be reserved only for javadoc. - PR Comment: https://git.openjdk.org/jdk/pull/18846#issuecomment-2066383735
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base`
On Thu, 18 Apr 2024 20:44:00 GMT, Jonathan Gibbons wrote: > Please review a set of updates to clean up use of `/**` comments in the > vicinity of declarations. > > There are various categories of update: > > * "Box comments" beginning with `/**` > * Misplaced doc comments before package or import statements > * Misplaced doc comments after the annotations for a declaration > * Dangling `/**` comments relating to a group of declarations, separate from > the doc comments for each of those declarations > * Use of `/**` for the legal header at or near the top of the file > > In one case, two doc comments before a declaration were merged, which fixes a > bug/omission in the documented serialized form. Changes to networking code looks good. I didn't spot any issue with the rest but I'm usually not a reviewer there. - Marked as reviewed by dfuchs (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/18846#pullrequestreview-2011186056
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base`
On Thu, 18 Apr 2024 20:44:00 GMT, Jonathan Gibbons wrote:
> Please review a set of updates to clean up use of `/**` comments in the
> vicinity of declarations.
>
> There are various categories of update:
>
> * "Box comments" beginning with `/**`
> * Misplaced doc comments before package or import statements
> * Misplaced doc comments after the annotations for a declaration
> * Dangling `/**` comments relating to a group of declarations, separate from
> the doc comments for each of those declarations
> * Use of `/**` for the legal header at or near the top of the file
>
> In one case, two doc comments before a declaration were merged, which fixes a
> bug/omission in the documented serialized form.
It is somewhat off-topic. Yet I noticed javadoc comments in some files are
followed a blank line, and others aren't. Out of my curiosity, is there a
convention about the blank line between the javadoc comment and the class or
interface declaration? Should there be one?
/**
* This is a class.
*/
public class A {}
or
/**
* This is a class.
*/
public class A {}
Which is the most common? Which is preferred?
-
PR Comment: https://git.openjdk.org/jdk/pull/18846#issuecomment-2066337900
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base`
On Thu, 18 Apr 2024 20:44:00 GMT, Jonathan Gibbons wrote:
> Please review a set of updates to clean up use of `/**` comments in the
> vicinity of declarations.
>
> There are various categories of update:
>
> * "Box comments" beginning with `/**`
> * Misplaced doc comments before package or import statements
> * Misplaced doc comments after the annotations for a declaration
> * Dangling `/**` comments relating to a group of declarations, separate from
> the doc comments for each of those declarations
> * Use of `/**` for the legal header at or near the top of the file
>
> In one case, two doc comments before a declaration were merged, which fixes a
> bug/omission in the documented serialized form.
src/java.base/macosx/classes/apple/security/AppleProvider.java line 33:
> 31: /*
> 32: * The Apple Security Provider.
> 33: */
Does it make sense to incorporate this comment into the following javadoc
comment?
/**
* Defines the (an) Apple security provider.
* ...
*/
@SuppressWarnings("serial") // JDK implementation class
src/java.base/share/classes/com/sun/crypto/provider/SunJCE.java line 37:
> 35: import static sun.security.util.SecurityProviderConstants.*;
> 36:
> 37: /*
Should this be included in the main javadoc comment? The `@author` tags belong
in the javadoc comment.
The javadoc itself is likely unreadable, when processed the entire comment
becomes one very long paragraph.
src/java.base/share/classes/sun/net/www/protocol/file/FileURLConnection.java
line 38:
> 36:
> 37: /**
> 38: * Open an file input stream given a URL.
Suggestion:
* Open a file input stream given a URL.
-
PR Review Comment: https://git.openjdk.org/jdk/pull/18846#discussion_r1572192780
PR Review Comment: https://git.openjdk.org/jdk/pull/18846#discussion_r1572184441
PR Review Comment: https://git.openjdk.org/jdk/pull/18846#discussion_r1572189001
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base`
On Thu, 18 Apr 2024 20:44:00 GMT, Jonathan Gibbons wrote: > Please review a set of updates to clean up use of `/**` comments in the > vicinity of declarations. > > There are various categories of update: > > * "Box comments" beginning with `/**` > * Misplaced doc comments before package or import statements > * Misplaced doc comments after the annotations for a declaration > * Dangling `/**` comments relating to a group of declarations, separate from > the doc comments for each of those declarations > * Use of `/**` for the legal header at or near the top of the file > > In one case, two doc comments before a declaration were merged, which fixes a > bug/omission in the documented serialized form. Marked as reviewed by iris (Reviewer). - PR Review: https://git.openjdk.org/jdk/pull/18846#pullrequestreview-2010068091
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base`
On Thu, 18 Apr 2024 20:44:00 GMT, Jonathan Gibbons wrote: > Please review a set of updates to clean up use of `/**` comments in the > vicinity of declarations. > > There are various categories of update: > > * "Box comments" beginning with `/**` > * Misplaced doc comments before package or import statements > * Misplaced doc comments after the annotations for a declaration > * Dangling `/**` comments relating to a group of declarations, separate from > the doc comments for each of those declarations > * Use of `/**` for the legal header at or near the top of the file > > In one case, two doc comments before a declaration were merged, which fixes a > bug/omission in the documented serialized form. Marked as reviewed by darcy (Reviewer). - PR Review: https://git.openjdk.org/jdk/pull/18846#pullrequestreview-2010059355
Re: RFR: 8330178: Clean up non-standard use of /** comments in `java.base`
On Thu, 18 Apr 2024 20:44:00 GMT, Jonathan Gibbons wrote: > Please review a set of updates to clean up use of `/**` comments in the > vicinity of declarations. > > There are various categories of update: > > * "Box comments" beginning with `/**` > * Misplaced doc comments before package or import statements > * Misplaced doc comments after the annotations for a declaration > * Dangling `/**` comments relating to a group of declarations, separate from > the doc comments for each of those declarations > * Use of `/**` for the legal header at or near the top of the file > > In one case, two doc comments before a declaration were merged, which fixes a > bug/omission in the documented serialized form. Should the copyright be updated? - PR Comment: https://git.openjdk.org/jdk/pull/18846#issuecomment-2065339389
RFR: 8330178: Clean up non-standard use of /** comments in `java.base`
Please review a set of updates to clean up use of `/**` comments in the vicinity of declarations. There are various categories of update: * "Box comments" beginning with `/**` * Misplaced doc comments before package or import statements * Misplaced doc comments after the annotations for a declaration * Dangling `/**` comments relating to a group of declarations, separate from the doc comments for each of those declarations * Use of `/**` for the legal header at or near the top of the file In one case, two doc comments before a declaration were merged, which fixes a bug/omission in the documented serialized form. - Commit messages: - JDK-8330178: Clean up non-standard use of /** comments in `java.base` Changes: https://git.openjdk.org/jdk/pull/18846/files Webrev: https://webrevs.openjdk.org/?repo=jdk=18846=00 Issue: https://bugs.openjdk.org/browse/JDK-8330178 Stats: 134 lines in 23 files changed: 50 ins; 56 del; 28 mod Patch: https://git.openjdk.org/jdk/pull/18846.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/18846/head:pull/18846 PR: https://git.openjdk.org/jdk/pull/18846
