RFR: 8331879: Clean up non-standard use of /// comments in `java.base` [v2]

[Iris Clark]

On Tue, 28 May 2024 22:31:15 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> With the advent of JEP 467, `///` comments may be treated as documentation comments, and may be subject to the recently new `javac` warning about "dangling doc comments" in unexpected places.
>> 
>> In keeping with the policy to keep the `java.base` module free of all `javac` warnings, this patch proposes edits to existing uses of `///`.
>> 
>> There are two dominant policies in the proposed changes. 
>> 1. A long horizontal line of `/////` is replaced by `//-----`
>> 2. A long vertical series of lines beginning `///` is replaced by lines beginning `//|`.
>> 
>> As with all style changes, I have also tried to honor local usage, for consistency.
>> 
>> In one place, a pair of comments appeared to contain directives (`CLOVER:ON`, `CLOVER:OFF`).  I investigated the use of such comments to determine that the exact form of the comment prefix was not significant. (Phew!)
>> 
>> 
>> (This PR is informally blocked by JEP 467).
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   incorporate review comments

Thanks for making these updates.

To my eye, replacement of "///" with "//---" is preferable over "//|", but I think either choice is acceptable.

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

Marked as reviewed by iris (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/19130#pullrequestreview-2091379761