On Tue, 28 May 2024 22:31:15 GMT, Jonathan Gibbons <j...@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
