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

[ExE Boss]

On Tue, 7 May 2024 22:23:48 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).

src/java.base/share/classes/jdk/internal/reflect/ClassFileAssembler.java line 206:

> 204:     //-------------
> 205:     // Constants //
> 206:     //-------------

Suggestion:

    //-----------//
    // Constants //
    //-----------//

src/java.base/share/classes/jdk/internal/reflect/ClassFileAssembler.java line 227:

> 225:     //-----------------------------------
> 226:     // Local variable loads and stores //
> 227:     //-----------------------------------

Suggestion:

    //---------------------------------//
    // Local variable loads and stores //
    //---------------------------------//

src/java.base/share/classes/jdk/internal/reflect/ClassFileAssembler.java line 411:

> 409:     //-----------------------------
> 410:     // Widening conversions only //
> 411:     //-----------------------------

Suggestion:

    //---------------------------//
    // Widening conversions only //
    //---------------------------//

src/java.base/share/classes/jdk/internal/reflect/ClassFileAssembler.java line 439:

> 437:     //----------------
> 438:     // Control flow //
> 439:     //----------------

Suggestion:

    //--------------//
    // Control flow //
    //--------------//

src/java.base/share/classes/jdk/internal/reflect/ClassFileAssembler.java line 519:

> 517:     //-----------------------
> 518:     // Return instructions //
> 519:     //-----------------------

Suggestion:

    //---------------------//
    // Return instructions //
    //---------------------//

src/java.base/share/classes/jdk/internal/reflect/ClassFileAssembler.java line 553:

> 551:     //--------------------
> 552:     // Field operations //
> 553:     //--------------------

Suggestion:

    //------------------//
    // Field operations //
    //------------------//

src/java.base/share/classes/jdk/internal/reflect/ClassFileAssembler.java line 581:

> 579:     //----------------------
> 580:     // Method invocations //
> 581:     //----------------------

Suggestion:

    //--------------------//
    // Method invocations //
    //--------------------//

src/java.base/share/classes/jdk/internal/reflect/ClassFileAssembler.java line 632:

> 630:     //----------------
> 631:     // Array length //
> 632:     //----------------

Suggestion:

    //--------------//
    // Array length //
    //--------------//

src/java.base/share/classes/jdk/internal/reflect/ClassFileAssembler.java line 640:

> 638:     //-------
> 639:     // New //
> 640:     //-------

Suggestion:

    //-----//
    // New //
    //-----//

src/java.base/share/classes/jdk/internal/reflect/ClassFileAssembler.java line 650:

> 648:     //----------
> 649:     // Athrow //
> 650:     //----------

Suggestion:

    //--------//
    // Athrow //
    //--------//

src/java.base/share/classes/jdk/internal/reflect/ClassFileAssembler.java line 659:

> 657:     //----------------------------
> 658:     // Checkcast and instanceof //
> 659:     //----------------------------

Suggestion:

    //--------------------------//
    // Checkcast and instanceof //
    //--------------------------//

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

PR Review Comment: https://git.openjdk.org/jdk/pull/19130#discussion_r1593971885
PR Review Comment: https://git.openjdk.org/jdk/pull/19130#discussion_r1593972168
PR Review Comment: https://git.openjdk.org/jdk/pull/19130#discussion_r1593972556
PR Review Comment: https://git.openjdk.org/jdk/pull/19130#discussion_r1593972931
PR Review Comment: https://git.openjdk.org/jdk/pull/19130#discussion_r1593973196
PR Review Comment: https://git.openjdk.org/jdk/pull/19130#discussion_r1593973651
PR Review Comment: https://git.openjdk.org/jdk/pull/19130#discussion_r1593974149
PR Review Comment: https://git.openjdk.org/jdk/pull/19130#discussion_r1593974540
PR Review Comment: https://git.openjdk.org/jdk/pull/19130#discussion_r1593974850
PR Review Comment: https://git.openjdk.org/jdk/pull/19130#discussion_r1593975284
PR Review Comment: https://git.openjdk.org/jdk/pull/19130#discussion_r1593975816