On Thu, 18 Apr 2024 20:44:00 GMT, Jonathan Gibbons <[email protected]> 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
