Location of jtreg tags in tests

[Aleksei Ivanov]

Hello fellow developers,

Most older tests have the jtreg tags before import statements.

As an example, JList/6462008/bug6462008.java [1] and 
JTextArea/4697612/bug4697612.java [2].

When you open such a test in an IDE, the jtreg tags are collapsed along 
with the copyright and license header. I find it inconvenient. The jtreg 
tags provide important information about the test: its summary, its 
keywords, its requirements and possible parameters.


Over the years, I've been asking people [3][4] to move the jtreg tags to 
the class declaration.

When the jtreg tags are before the class declaration (below the import 
statements), they're not collapsed, which means you see all the jtreg 
tags when you open a test file in the IDE without additional navigation 
or mouse movements.


There were a couple of discussions around this matter [5][6]. No 
decision has been made.

This message is a call for discussion so that we, the client libraries 
developers, agree on a common style.

I propose putting the jtreg tags right above the test class declaration:

import javax.swing.JFrame;

/*
  * @test
  * @bug <bugids>
  * @key headful
  * @summary <description of the test>
  */
public final class SampleTest {


The comment with jtreg tags immediately precedes the test class 
declaration. There's no blank line between the comment and the 
declaration. The comment uses a regular block comment syntax with the 
single asterisk ‘/*’ (as opposed to a javadoc comment which starts with 
double asterisk ‘/**’).

I also propose establishing an order for the tags for consistency [7]. 
Most tests have a convention, the tags usually appear in the following 
order:

@test
@bug
@key
@summary
@library
@build
@run


In addition to that, manual tests do not need ‘@key headful’ because 
“all manual tests are assumed to be headful.” [8]


What do you think?

-- 
Regards,
Alexey

[1] 
https://github.com/openjdk/jdk/blob/70e7cdcb9ecedd455cf701b5c7ad05286ac0067d/test/jdk/javax/swing/JList/6462008/bug6462008.java#L24-L31
[2] 
https://github.com/openjdk/jdk/blob/70e7cdcb9ecedd455cf701b5c7ad05286ac0067d/test/jdk/javax/swing/JTextArea/4697612/bug4697612.java#L24-L29
[3] https://github.com/openjdk/jdk/pull/12180#discussion_r1100013426
[4] https://github.com/openjdk/jdk/pull/11940#discussion_r1102835163
[5] https://github.com/openjdk/jdk/pull/16674#discussion_r1402082665
[6] https://github.com/openjdk/jdk/pull/16785#discussion_r1410944165
[7] https://github.com/openjdk/jdk/pull/16785#discussion_r1403301368
[8] 
https://github.com/prrace/jdk/blob/91d8ea79d947aa7dad91d8ed550ed34a7d49d885/test/jdk/TEST.ROOT#L27