RFR: 7903188: Log time spent waiting to acquire exclusive access lock [v2]

[Jonathan Gibbons]

On Wed, 3 Jul 2024 03:53:23 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

>> src/share/classes/com/sun/javatest/regtest/config/RegressionTestSuite.java line 220:
>> 
>>> 218:     /**
>>> 219:      * @param td the test description
>>> 220:      * {@return true if the test is configured to run exclusively, false otherwise}
>> 
>> This is in the wrong place.
>> As written, the inline tag `{@return...}` is part of the description of the preceding block tag `@param`
>> 
>> When using the inline form of the `return` tag, it should appear at the beginning of the description.
>
> Hello Jon, I wasn't aware of this. I've now moved the `{@return}` to place it before the `@param`.

Generally, the format of a doc comment is an initial _description_ followed by _block tags_.  Block tags begin with `@` at the beginning of a line. Some (but not all) block tags may also contain descriptions, perhaps after some other token (e.g. `@param`  `@throws`).
Descriptions are typically composed of plain text, HTML elements, and _inline tags_. Inline tags are all of the form `{@`_name_ _optional-args_`}` -- and soon, depending on the doc comment, Markdown constructs.  Some inline tags (`{@return...}` and `{@summary ...}`) must appear at the beginning of the initial description.

For more info, see the Doc Comment Specification in the main JDK docs, such as [here](https://docs.oracle.com/en/java/javase/21/docs/specs/javadoc/doc-comment-spec.html)
You can generally always find this with either a Google search or a search in the JDK API search box for "Doc Comment Spec".

-------------

PR Review Comment: https://git.openjdk.org/jtreg/pull/208#discussion_r1664874362