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.
SWinxy On Thu, Feb 1, 2024 at 10:48 AM Aleksei Ivanov <[email protected]> wrote: > 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 >
