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

[Jonathan Gibbons]

On Wed, 3 Jul 2024 22:24:07 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> 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".

FWIW, the inline form `{@return `_description_`}` is just a short form for
`Returns` _description_ `.`
@return description

which is a common but repetitive idiom in doc comments.

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

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