[jfx17] Integrated: 8271086: Block comments of form '/***' are treated as javadoc comments

[Kevin Rushforth]

On Thu, 22 Jul 2021 22:07:34 GMT, Kevin Rushforth <kcr at openjdk.org> wrote:

> This fix for [JDK-8271086](https://bugs.openjdk.java.net/browse/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](https://bugs.openjdk.java.net/browse/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](https://openjfx.io/javadoc/16/javafx.graphics/javafx/scene/Node.html#getNodeOrientation%28%29) 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`.

This pull request has now been integrated.

Changeset: 78a3721a
Author:    Kevin Rushforth <kcr at openjdk.org>
URL:       https://git.openjdk.java.net/jfx/commit/78a3721a2b126e174b5fd94ea1d15ccdbe6d3624
Stats:     982 lines in 185 files changed: 0 ins; 0 del; 982 mod

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

Reviewed-by: arapte

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

PR: https://git.openjdk.java.net/jfx/pull/585