Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Closed

Conversation

@kevinrushforth
Copy link
Member

@kevinrushforth kevinrushforth commented Jul 22, 2021

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

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
Copy link

@bridgekeeper bridgekeeper bot commented Jul 22, 2021

👋 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.

Loading

@openjdk openjdk bot changed the title 8271086 8271086: Block comments of form '/***' are treated as javadoc comments Jul 22, 2021
@openjdk openjdk bot added the rfr label Jul 22, 2021
@mlbridge
Copy link

@mlbridge mlbridge bot commented Jul 22, 2021

Webrevs

Loading

@kevinrushforth kevinrushforth requested a review from aghaisas Jul 27, 2021
arapte
arapte approved these changes Jul 28, 2021
Copy link
Member

@arapte arapte left a comment

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

Loading

@openjdk
Copy link

@openjdk openjdk bot commented Jul 28, 2021

@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.

Loading

@openjdk openjdk bot added the ready label Jul 28, 2021
@kevinrushforth
Copy link
Member Author

@kevinrushforth kevinrushforth commented Jul 28, 2021

/integrate

Loading

@openjdk
Copy link

@openjdk openjdk bot commented Jul 28, 2021

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.

Loading

@openjdk openjdk bot closed this Jul 28, 2021
@openjdk openjdk bot added integrated and removed ready rfr labels Jul 28, 2021
@openjdk
Copy link

@openjdk openjdk bot commented Jul 28, 2021

@kevinrushforth Pushed as commit 78a3721.

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

Loading

@kevinrushforth kevinrushforth deleted the 8271086-block-comments branch Jul 28, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
2 participants