JDK-8189591: No way to locally suppress doclint warnings

[jonathan-gibbons]

Please review a moderately simple change, to have DocLint check for relevant @SuppressWarnings annotations before reporting any messages.

---

Progress

• Change must not contain extraneous whitespace
• Commit message must refer to an issue
• Change must be properly reviewed

Issue

• JDK-8189591: No way to locally suppress doclint warnings

Reviewers

• Hannes Wallnöfer (@hns - Reviewer) ⚠️ Review applies to 6938a7a
• Pavel Rappo (@pavelrappo - Reviewer) ⚠️ Review applies to 6938a7a

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk pull/5870/head:pull/5870
$ git checkout pull/5870

Update a local copy of the PR:
$ git checkout pull/5870
$ git pull https://git.openjdk.java.net/jdk pull/5870/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 5870

View PR using the GUI difftool:
$ git pr show -t 5870

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jdk/pull/5870.diff

[bridgekeeper]

👋 Welcome back jjg! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[jonathan-gibbons]

/csr

[openjdk]

@jonathan-gibbons this pull request will not be integrated until the CSR request JDK-8274926 for issue JDK-8189591 has been approved.

[openjdk]

@jonathan-gibbons The following labels will be automatically applied to this pull request:

• compiler
• javadoc

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.

[mlbridge]

Webrevs

• 01: Full - Incremental (6e736b69)
• 00: Full (6938a7ac)

[hns]

Very nice! Looks good to me.

[mlbridge]

Mailing list message from Joseph D. Darcy on compiler-dev:

On 10/12/2021 8:28 AM, Jonathan Gibbons wrote:

On Tue, 12 Oct 2021 15:11:13 GMT, Hannes Walln?fer <hannesw at openjdk.org> wrote:

Please review a moderately simple change, to have DocLint check for relevant `@SuppressWarnings` annotations before reporting any messages.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Env.java line 302:

300: for (String a: arg.substring(len).split(",")) {
301: Messages.Group argGroup = gMap.get(a);
302: if (argGroup != null) {
Should we let the user know about unknown doclint:* values?
I thought about this, but in general, the precedent in `SuppressWarnings` is to not reject unknown values, because they might be supported by other systems.

One special case of other system can be the JDK used for bootstrapping
in the JDK build.

-Joe

[openjdk]

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

8189591: No way to locally suppress doclint warnings

Reviewed-by: hannesw, prappo

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 83 new commits pushed to the master branch:

• 7fc3a8d: 8275149: (ch) ReadableByteChannel returned by Channels.newChannel(InputStream) throws ReadOnlyBufferException
• 831802d: 8275163: Deflater::deflate methods omit javadoc for ReadOnlyBufferException
• ad9e234: 8275145: file.encoding system property has an incorrect value on Windows
• f178185: 8275249: Suppress warnings on non-serializable array component types in jdk.jlink
• ee64ce9: 8274937: Revert the timeout setting for DynamicLoaderConstraintsTest
• 8c4da9c: 8275013: Improve discussion of serialization method declarations in java.io.Object{Input, Output}Stream
• da8da3a: 8269698: Specification for methods of java.awt.im.InputContext should mention that they do nothing
• 8e02064: 8049520: FileCredentialsCache loads cache once and is never refreshed
• 172aed1: 8274338: com/sun/jdi/RedefineCrossEvent.java failed "assert(m != __null) failed: NULL mirror"
• ced7909: 8275286: Check current thread when calling JRT methods that expect it
• ... and 73 more: https://git.openjdk.java.net/jdk/compare/ec199072c5867624d66840238cc8828e16ae8da7...master

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 master branch, type /integrate in a new comment.

[pavelrappo]

Looks good; consider the trivial suggestions below.

[jonathan-gibbons]

/integrate

[openjdk]

Going to push as commit 96fef40.
Since your change was applied there have been 83 commits pushed to the master branch:

• 7fc3a8d: 8275149: (ch) ReadableByteChannel returned by Channels.newChannel(InputStream) throws ReadOnlyBufferException
• 831802d: 8275163: Deflater::deflate methods omit javadoc for ReadOnlyBufferException
• ad9e234: 8275145: file.encoding system property has an incorrect value on Windows
• f178185: 8275249: Suppress warnings on non-serializable array component types in jdk.jlink
• ee64ce9: 8274937: Revert the timeout setting for DynamicLoaderConstraintsTest
• 8c4da9c: 8275013: Improve discussion of serialization method declarations in java.io.Object{Input, Output}Stream
• da8da3a: 8269698: Specification for methods of java.awt.im.InputContext should mention that they do nothing
• 8e02064: 8049520: FileCredentialsCache loads cache once and is never refreshed
• 172aed1: 8274338: com/sun/jdi/RedefineCrossEvent.java failed "assert(m != __null) failed: NULL mirror"
• ced7909: 8275286: Check current thread when calling JRT methods that expect it
• ... and 73 more: https://git.openjdk.java.net/jdk/compare/ec199072c5867624d66840238cc8828e16ae8da7...master

Your commit was automatically rebased without conflicts.

[openjdk]

@jonathan-gibbons Pushed as commit 96fef40.

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