[prev in list] [next in list] [prev in thread] [next in thread] 

List:       openjdk-openjfx-dev
Subject:    Re: [jfx17] RFR: 8271086: Block comments of form '/***' are treated as javadoc comments
From:       Ambarish Rapte <arapte () openjdk ! java ! net>
Date:       2021-07-28 17:22:32
Message-ID: TE243Y2fabkYGbupS0xn-qCKEzwZ_z6IVieSVI2s_cM=.35ed8400-875f-4515-b484-f5bbd10909fa () github ! com
[Download RAW message or body]

On Thu, 22 Jul 2021 22:07:34 GMT, Kevin Rushforth <kcr@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


[prev in list] [next in list] [prev in thread] [next in thread]