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

[Jonathan Gibbons]

On Fri, 19 Apr 2024 11:32:55 GMT, Pavel Rappo <prappo at openjdk.org> 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