<div dir="ltr">This is a sound manual of style proposal. At some point I'd like all the tests to conform to this. I would add on to say that @summary should be a mandatory field, as the test in [2] lacks a short description.<div><br></div><div>SWinxy</div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Feb 1, 2024 at 10:48 AM Aleksei Ivanov <<a href="mailto:alexey.ivanov@oracle.com">alexey.ivanov@oracle.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Hello fellow developers,<br>
<br>
Most older tests have the jtreg tags before import statements.<br>
<br>
As an example, JList/6462008/bug6462008.java [1] and <br>
JTextArea/4697612/bug4697612.java [2].<br>
<br>
When you open such a test in an IDE, the jtreg tags are collapsed along <br>
with the copyright and license header. I find it inconvenient. The jtreg <br>
tags provide important information about the test: its summary, its <br>
keywords, its requirements and possible parameters.<br>
<br>
<br>
Over the years, I've been asking people [3][4] to move the jtreg tags to <br>
the class declaration.<br>
<br>
When the jtreg tags are before the class declaration (below the import <br>
statements), they're not collapsed, which means you see all the jtreg <br>
tags when you open a test file in the IDE without additional navigation <br>
or mouse movements.<br>
<br>
<br>
There were a couple of discussions around this matter [5][6]. No <br>
decision has been made.<br>
<br>
This message is a call for discussion so that we, the client libraries <br>
developers, agree on a common style.<br>
<br>
I propose putting the jtreg tags right above the test class declaration:<br>
<br>
import javax.swing.JFrame;<br>
<br>
/*<br>
  * @test<br>
  * @bug <bugids><br>
  * @key headful<br>
  * @summary <description of the test><br>
  */<br>
public final class SampleTest {<br>
<br>
<br>
The comment with jtreg tags immediately precedes the test class <br>
declaration. There's no blank line between the comment and the <br>
declaration. The comment uses a regular block comment syntax with the <br>
single asterisk ‘/*’ (as opposed to a javadoc comment which starts with <br>
double asterisk ‘/**’).<br>
<br>
I also propose establishing an order for the tags for consistency [7]. <br>
Most tests have a convention, the tags usually appear in the following <br>
order:<br>
<br>
@test<br>
@bug<br>
@key<br>
@summary<br>
@library<br>
@build<br>
@run<br>
<br>
<br>
In addition to that, manual tests do not need ‘@key headful’ because <br>
“all manual tests are assumed to be headful.” [8]<br>
<br>
<br>
What do you think?<br>
<br>
-- <br>
Regards,<br>
Alexey<br>
<br>
[1] <br>
<a href="https://github.com/openjdk/jdk/blob/70e7cdcb9ecedd455cf701b5c7ad05286ac0067d/test/jdk/javax/swing/JList/6462008/bug6462008.java#L24-L31" rel="noreferrer" target="_blank">https://github.com/openjdk/jdk/blob/70e7cdcb9ecedd455cf701b5c7ad05286ac0067d/test/jdk/javax/swing/JList/6462008/bug6462008.java#L24-L31</a><br>
[2] <br>
<a href="https://github.com/openjdk/jdk/blob/70e7cdcb9ecedd455cf701b5c7ad05286ac0067d/test/jdk/javax/swing/JTextArea/4697612/bug4697612.java#L24-L29" rel="noreferrer" target="_blank">https://github.com/openjdk/jdk/blob/70e7cdcb9ecedd455cf701b5c7ad05286ac0067d/test/jdk/javax/swing/JTextArea/4697612/bug4697612.java#L24-L29</a><br>
[3] <a href="https://github.com/openjdk/jdk/pull/12180#discussion_r1100013426" rel="noreferrer" target="_blank">https://github.com/openjdk/jdk/pull/12180#discussion_r1100013426</a><br>
[4] <a href="https://github.com/openjdk/jdk/pull/11940#discussion_r1102835163" rel="noreferrer" target="_blank">https://github.com/openjdk/jdk/pull/11940#discussion_r1102835163</a><br>
[5] <a href="https://github.com/openjdk/jdk/pull/16674#discussion_r1402082665" rel="noreferrer" target="_blank">https://github.com/openjdk/jdk/pull/16674#discussion_r1402082665</a><br>
[6] <a href="https://github.com/openjdk/jdk/pull/16785#discussion_r1410944165" rel="noreferrer" target="_blank">https://github.com/openjdk/jdk/pull/16785#discussion_r1410944165</a><br>
[7] <a href="https://github.com/openjdk/jdk/pull/16785#discussion_r1403301368" rel="noreferrer" target="_blank">https://github.com/openjdk/jdk/pull/16785#discussion_r1403301368</a><br>
[8] <br>
<a href="https://github.com/prrace/jdk/blob/91d8ea79d947aa7dad91d8ed550ed34a7d49d885/test/jdk/TEST.ROOT#L27" rel="noreferrer" target="_blank">https://github.com/prrace/jdk/blob/91d8ea79d947aa7dad91d8ed550ed34a7d49d885/test/jdk/TEST.ROOT#L27</a><br>
</blockquote></div>