-
Notifications
You must be signed in to change notification settings - Fork 5.5k
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
8303689: javac -Xlint could/should report on "dangling" doc comments #18527
8303689: javac -Xlint could/should report on "dangling" doc comments #18527
Conversation
👋 Welcome back jjg! A progress list of the required criteria for merging this PR into |
@jonathan-gibbons 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:
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 15 new commits pushed to the
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 |
@jonathan-gibbons The following labels will be automatically applied to this pull request:
When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command. |
Webrevs
|
Would this be the first lint -- not doclint -- warning related to comments, let alone doc comments? |
Javadoc changes look trivially good. I only note that the javadoc man page diff contains some unrelated changes. |
To check for any extra or misplaced documentation comments, compile your | ||
source code with the \f[V]javac\f[R] option \f[V]-Xlint\f[R], or more | ||
specifically, \f[V]-Xlint:dangling-doc-comments\f[R]. | ||
Within a source file, you may use suppress any warnings generated by |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Typo?
Within a source file, you may use suppress any warnings generated by | |
Within a source file, you may suppress any warnings generated by |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks; I'll check/fix the underlying original.
No. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
lgtm
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The build changes look okay.
Do you have any plan of going through all the Java modules and fixing the issues, or opening JBS issues to have them fixed? Or will these lint warnings remain disabled for the foreseeable future?
The plan is to create an umbrella bug to clean up the individual modules. There is interest to clean up |
suppress warning when building test code
@jonathan-gibbons this pull request can not be integrated into git checkout 8303689.dangling-comments
git fetch https://git.openjdk.org/jdk.git master
git merge FETCH_HEAD
# resolve conflicts and follow the instructions given by git merge
git commit -m "Merge master"
git push |
…comments # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
looks good
src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavacParser.java
Outdated
Show resolved
Hide resolved
/integrate |
Going to push as commit a920af2.
Your commit was automatically rebased without conflicts. |
@jonathan-gibbons Pushed as commit a920af2. 💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored. |
Please review the updates to support a proposed new
-Xlint:dangling-doc-comments
option.The work can be thought of as in 3 parts:
An update to the
javac
internal classDeferredLintHandler
so that it is possible to specify the appropriately configuredLint
object when it is time to consider whether to generate the diagnostic or not.Updates to the
javac
front end to record "dangling docs comments" found near the beginning of a declaration, and to report them using an instance ofDeferredLintHandler
. This allows the warnings to be enabled or disabled using the standard mechanisms for-Xlint
and@SuppressWarnings
. The procedure for handling dangling doc comments is described in this comment inJavacParser
.warning is generated. This is often because of the confusing use of
/**
tocreate box or other standout comments.
Progress
Issues
Reviewers
Reviewing
Using
git
Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
$ git checkout pull/18527
Update a local copy of the PR:
$ git checkout pull/18527
$ git pull https://git.openjdk.org/jdk.git pull/18527/head
Using Skara CLI tools
Checkout this PR locally:
$ git pr checkout 18527
View PR using the GUI difftool:
$ git pr show -t 18527
Using diff file
Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/18527.diff
Webrev
Link to Webrev Comment