Location of jtreg tags in tests

[SWinxy]

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 <alexey.ivanov at oracle.com>
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
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/client-libs-dev/attachments/20240209/8d6f267f/attachment.htm>