8271086: Block comments of form '/***' are treated as javadoc comments

[kevinrushforth]

This fix for JDK-8271086 is part of a larger cleanup effort to find and fix places where we have missing or redundant API comments. See JDK-8271083.

This fixes a long-standing problem dating back to (at least) JavaFX 2 where block comments of the following form are sometimes treated as javadoc comments:

    /***************************************************************************
     * ...
     **************************************************************************/

There are several places where a block comment like this unintentionally shows up in our API documentation. For example, see the generated docs for Node::getNodeOrientation where the literal string * Component Orientation Properties * * is presented in the docs.

The best solution is to simply eliminate this style of block comment as an anti-pattern everywhere it occurs in our Java code.

There are a total of 982 such occurrences (in 185 different files). All but 7 of these follow the pattern shown above, where the trimmed first line of the block is a single / followed by 4 or more * characters, and contains no other characters. Like this:

    /***************************************************************************

The remaining 7 are comments with some variation, either being an inline comment (starting with //) or having text in the middle, or in one case is intended to be a javadoc comment, but with an extra * -- /*** rather than /**. I fixed those 7 manually and then ran a script to fix the remaining 975 comments, by replacing the 2nd * with a space (thus preserving the line length).

So:

    /***************************************************************************

becomes

    /* *************************************************************************

Notes to Reviewers

1. The 7 manual changes are in the first commit, and the automated changes are in the second comment. I have run a build + sanity test, and I did a diff of the generated API docs generated by gradle javadoc and also visually inspected the docs (spot checked), and confirmed that it fixes the problem.
2. This is targeted to jfx17.

---

Progress

• Change must not contain extraneous whitespace
• Commit message must refer to an issue
• Change must be properly reviewed

Issue

• JDK-8271086: Block comments of form '/***' are treated as javadoc comments

Reviewers

• Ambarish Rapte (@arapte - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jfx pull/585/head:pull/585
$ git checkout pull/585

Update a local copy of the PR:
$ git checkout pull/585
$ git pull https://git.openjdk.java.net/jfx pull/585/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 585

View PR using the GUI difftool:
$ git pr show -t 585

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jfx/pull/585.diff

[bridgekeeper]

👋 Welcome back kcr! A progress list of the required criteria for merging this PR into jfx17 will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[mlbridge]

Webrevs

• 00: Full (a80e11f0)

[arapte]

Looks good to me, verified javadoc build and doc. This is correcting plenty wrong docs.

[openjdk]

@kevinrushforth This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8271086: Block comments of form '/***' are treated as javadoc comments

Reviewed-by: arapte

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 3 new commits pushed to the jfx17 branch:

• 2cd5d1f: 8240640: [macos] Wrong focus behaviour with multiple Alerts
• 0e5b788: 8271230: Remove obsolete test classes and data files from 3DViewer sample
• d540109: 8270959: Update boot JDK to 16.0.2

Please see this link for an up-to-date comparison between the source branch of this pull request and the jfx17 branch.
As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the jfx17 branch, type /integrate in a new comment.

[kevinrushforth]

/integrate

[openjdk]

Going to push as commit 78a3721.
Since your change was applied there have been 3 commits pushed to the jfx17 branch:

• 2cd5d1f: 8240640: [macos] Wrong focus behaviour with multiple Alerts
• 0e5b788: 8271230: Remove obsolete test classes and data files from 3DViewer sample
• d540109: 8270959: Update boot JDK to 16.0.2

Your commit was automatically rebased without conflicts.

[openjdk]

@kevinrushforth Pushed as commit 78a3721.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.