On Fri, 19 Apr 2024 11:32:55 GMT, Pavel Rappo <pra...@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
