RFR: 8331879: Clean up non-standard use of /// comments in `java.base`
Jonathan Gibbons
jjg at openjdk.org
Tue May 28 18:53:02 UTC 2024
On Wed, 22 May 2024 20:13:08 GMT, Naoto Sato <naoto 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).
>
> src/java.base/share/classes/jdk/internal/icu/impl/StringPrepDataReader.java line 122:
>
>> 120: * see store.c of gennorm for more information and values
>> 121: */
>> 122: // /* dataFormat="SPRP" 0x53, 0x50, 0x52, 0x50 */
>
> This source file is coming from the upstream ICU4J project. Even if this is a `non-standard` comment, I would keep it as it is to minimize the merge effort.
As a non-standard comment, it will trigger a warning, since the prevailing standard for `java.base` is to compile with all warnings enabled and no warnings found.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/19130#discussion_r1617755455
More information about the core-libs-dev
mailing list