On Thu, 22 Jul 2021 22:07:34 GMT, Kevin Rushforth <k...@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`. Looks good to me, verified javadoc build and doc. This is correcting plenty wrong docs. ------------- Marked as reviewed by arapte (Reviewer). PR: https://git.openjdk.java.net/jfx/pull/585
