jtreg test comments: /* vs /** usage

[Daniel Fuchs]

Hi Daisuke,

Generally regular /* */ comments would be preferred nowadays,
but bad habits die hard ;-(
I might have been responsible for a few of the now discouraged
javadoc /** */ style.

best regards,

-- daniel

On 08/12/2025 07:06, Alan Bateman wrote:
> On 07/12/2025 18:23, Daisuke Yamazaki wrote:
>> Hello all,
>>
>> I noticed that in most jtreg tests, the standard block comment `/* ... */` is
>> used for the test directives.
>> This is also what official jtreg documentation shows.
>>
>> However, in some older tests[1], for example QUIC-related tests[2],
>> I see`/** ... */` being used instead of `/* ... */`.
>>
>> Is there any specific reason for using JavaDoc-style comments (`/** ... */`) in
>> these tests?
>> Are there cases where `/**` beginning is preferred over the regular block
>> comment for jtreg directives?
>>
> jtreg (via the JT harness) looks for @test as the first token in /* .. 
> */ comments and doc comments /** .. */.  The examples in the tag spec 
> [1] use traditional comments but the test suites in openjdk/jdk have a 
> mix. I don't recall any discussion about making this a style issue and 
> trying to be consistent.
> 
> -Alan
> 
> [1] https://openjdk.org/jtreg/tag-spec.html