<i18n dev> RFR: 8330178: Clean up non-standard use of /** comments in `java.base`

[Pavel Rappo]

On Thu, 18 Apr 2024 20:44:00 GMT, Jonathan Gibbons <jjg at openjdk.org> 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