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`.
-------------
Commit messages:
- (automated) 8271086: Block comments of form '/***' are treated as javadoc
comments
- (manual) 8271086: Block comments of form '/***' are treated as javadoc
comments
Changes: https://git.openjdk.java.net/jfx/pull/585/files
Webrev: https://webrevs.openjdk.java.net/?repo=jfx&pr=585&range=00
Issue: https://bugs.openjdk.java.net/browse/JDK-8271086
Stats: 982 lines in 185 files changed: 0 ins; 0 del; 982 mod
Patch: https://git.openjdk.java.net/jfx/pull/585.diff
Fetch: git fetch https://git.openjdk.java.net/jfx pull/585/head:pull/585
PR: https://git.openjdk.java.net/jfx/pull/585
