8264779: Fix doclint warnings in java/nio #3376

c-cleary · 2021-04-07T13:22:44Z

This fix addresses the following warnings which were generated by building JDK API documentation with the -Xdoclint:all option enabled:

./build/linux-x64/support/gensrc/java.base/java/nio/charset/IllegalCharsetNameException.java:47: warning: no comment
    private String charsetName;
                   ^
./open/src/java.base/share/classes/java/nio/charset/MalformedInputException.java:44: warning: no comment
    private int inputLength;
                ^
./open/src/java.base/share/classes/java/nio/charset/UnmappableCharacterException.java:44: warning: no comment
    private int inputLength;
                ^
./build/linux-x64/support/gensrc/java.base/java/nio/charset/UnsupportedCharsetException.java:47: warning: no comment
    private String charsetName;
                   ^
./open/src/java.base/share/classes/java/nio/file/DirectoryIteratorException.java:81: warning: no @param for s
    private void readObject(ObjectInputStream s)
                 ^
./open/src/java.base/share/classes/java/nio/file/DirectoryIteratorException.java:81: warning: no @throws for java.lang.ClassNotFoundException
    private void readObject(ObjectInputStream s)
                 ^
./open/src/java.base/share/classes/java/nio/file/FileSystemException.java:43: warning: no comment
    private final String file;
                         ^
./open/src/java.base/share/classes/java/nio/file/FileSystemException.java:44: warning: no comment
    private final String other;
                         ^
./open/src/java.base/share/classes/java/nio/file/InvalidPathException.java:43: warning: no comment
    private int index;
                ^
./open/src/java.base/share/classes/java/nio/file/InvalidPathException.java:42: warning: no comment
    private String input;
                   ^
./open/src/java.base/share/classes/java/nio/file/attribute/UserPrincipalNotFoundException.java:43: warning: no comment
    private final String name;
                         ^

Changes to genExceptions.sh and the two exceptions templates are to address the warnings concerned with UnsupportedCharsetException.java and IllegalCharsetNameException.java which are generated when make jdk-image is run.

CSR: https://bugs.openjdk.java.net/browse/JDK-8264844

Progress

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

Issue

JDK-8264779: Fix doclint warnings in java/nio

Reviewers

Chris Hegarty (@ChrisHegarty - Reviewer) ⚠️ Review applies to b729d8e
Iris Clark (@irisclark - Reviewer) ⚠️ Review applies to 0b879f1
Alan Bateman (@AlanBateman - Reviewer) ⚠️ Review applies to 0b879f1
Naoto Sato (@naotoj - Reviewer)

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 3376

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

Using diff file

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

bridgekeeper · 2021-04-07T13:23:31Z

👋 Welcome back ccleary! 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.

c-cleary · 2021-04-07T13:26:06Z

/csr

openjdk · 2021-04-07T13:27:13Z

@c-cleary has indicated that a compatibility and specification (CSR) request is needed for this pull request.
@c-cleary please create a CSR request and add link to it in JDK-8264779. This pull request cannot be integrated until the CSR request is approved.

openjdk · 2021-04-07T13:29:03Z

@c-cleary The following label will be automatically applied to this pull request:

build

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

mlbridge · 2021-04-07T13:33:12Z

Webrevs

AlanBateman · 2021-04-07T13:41:24Z

/label add nio

openjdk · 2021-04-07T13:42:03Z

@AlanBateman
The nio label was successfully added.

AlanBateman · 2021-04-07T13:45:43Z

src/java.base/share/classes/java/nio/file/InvalidPathException.java

@@ -39,7 +39,15 @@
    @java.io.Serial
    static final long serialVersionUID = 4355821422286746137L;

+    /**
+     * The invalid input path string.
+     */


This should probably be "The input string" to be consistent with the getInput method.

AlanBateman · 2021-04-07T13:48:00Z

src/java.base/share/classes/java/nio/file/attribute/UserPrincipalNotFoundException.java

@@ -40,6 +40,9 @@
    @java.io.Serial
    static final long serialVersionUID = -5369283889045833024L;

+    /**
+     * The name of the {@code UserPrincipal} that does not exist.


Probably best to use "user principal name" so that it is consistent with getName.

Thanks Alan, will update as you suggest shortly with respect to both of your comments (also thanks for adding the nio label!)

naotoj · 2021-04-07T16:09:22Z

src/java.base/share/classes/java/nio/charset/MalformedInputException.java

@@ -41,6 +41,9 @@
    @java.io.Serial
    private static final long serialVersionUID = -3438823399834806194L;

+    /**
+     * The length of the input byte sequence.


Should this comment also refer to the character sequence?

It could, maybe something like "The length of the input byte (or character) sequence." would work?

or just "The length of the input" so that it is consistent with the description of the getInputLength method.

That sounds good.

Changed to "The length of the input." in the most recent commit.

src/java.base/share/classes/java/nio/charset/exceptions

src/java.base/share/classes/java/nio/exceptions

openjdk · 2021-04-08T21:21:56Z

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

8264779: Fix doclint warnings in java/nio

Reviewed-by: chegar, iris, alanb, naoto

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

3e57924: 8264885: Fix the code style of macro in aarch64_neon_ad.m4
051c117: 8264923: PNGImageWriter.write_zTXt throws Exception with a typo
1c6b113: 8264513: Cleanup CardTableBarrierSetC2::post_barrier
666fd62: 8264881: Remove the old development option MemProfiling
951f277: 8264874: Build interim-langtools for HotSpot only if Graal is enabled
719f95e: 8260693: Provide the support for specifying a signer in keytool -genkeypair
77b1673: 8256245: AArch64: Implement Base64 decoding intrinsic
57f1e7d: 8264696: Multi-catch clause causes compiler exception because it uses the package-private supertype
3d2b4cc: 8264864: Multiple byte tag not supported by ASN.1 encoding
ccefa5e: 8261625: Add Elements.isAutomaticModule(ModuleElement)
... and 31 more: https://git.openjdk.java.net/jdk/compare/4bb80f3720936d0cd9836e4f9c7233d2b4d8eee3...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.

As you do not have Committer status in this project an existing Committer must agree to sponsor your change. Possible candidates are the reviewers of this PR (@ChrisHegarty, @irisclark, @AlanBateman, @naotoj) but any other Committer may sponsor as well.

➡️ To flag this PR as ready for integration with the above commit message, type /integrate in a new comment. (Afterwards, your sponsor types /sponsor in a new comment to perform the integration).

c-cleary · 2021-04-09T07:27:38Z

/integrate

openjdk · 2021-04-09T07:28:41Z

@c-cleary
Your change (at version 9f36eec) is now ready to be sponsored by a Committer.

ChrisHegarty · 2021-04-09T08:49:49Z

/sponsor

openjdk · 2021-04-09T08:51:07Z

@ChrisHegarty @c-cleary Since your change was applied there have been 41 commits pushed to the master branch:

3e57924: 8264885: Fix the code style of macro in aarch64_neon_ad.m4
051c117: 8264923: PNGImageWriter.write_zTXt throws Exception with a typo
1c6b113: 8264513: Cleanup CardTableBarrierSetC2::post_barrier
666fd62: 8264881: Remove the old development option MemProfiling
951f277: 8264874: Build interim-langtools for HotSpot only if Graal is enabled
719f95e: 8260693: Provide the support for specifying a signer in keytool -genkeypair
77b1673: 8256245: AArch64: Implement Base64 decoding intrinsic
57f1e7d: 8264696: Multi-catch clause causes compiler exception because it uses the package-private supertype
3d2b4cc: 8264864: Multiple byte tag not supported by ASN.1 encoding
ccefa5e: 8261625: Add Elements.isAutomaticModule(ModuleElement)
... and 31 more: https://git.openjdk.java.net/jdk/compare/4bb80f3720936d0cd9836e4f9c7233d2b4d8eee3...master

Your commit was automatically rebased without conflicts.

Pushed as commit a45733f.

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

c-cleary added 3 commits April 7, 2021 10:45

8264779: Fix doclint warnings in java/nio

bc971af

8264779: Update copyrights and formatting

ec8727b

8264779: Doc fixes to generated exceptions

b729d8e

openjdk bot added the rfr Pull request is ready for review label Apr 7, 2021

openjdk bot added the csr Pull request needs approved CSR before integration label Apr 7, 2021

openjdk bot added the build build-dev@openjdk.org label Apr 7, 2021

ChrisHegarty approved these changes Apr 7, 2021

View reviewed changes

openjdk bot added the nio nio-dev@openjdk.org label Apr 7, 2021

AlanBateman reviewed Apr 7, 2021

View reviewed changes

8264779: Simplified comments

0b879f1

irisclark approved these changes Apr 7, 2021

View reviewed changes

naotoj reviewed Apr 7, 2021

View reviewed changes

AlanBateman approved these changes Apr 7, 2021

View reviewed changes

8264779: Shortened parameter comment

9f36eec

naotoj approved these changes Apr 7, 2021

View reviewed changes

openjdk bot removed the csr Pull request needs approved CSR before integration label Apr 8, 2021

openjdk bot added the ready Pull request is ready to be integrated label Apr 8, 2021

openjdk bot added the sponsor Pull request is ready to be sponsored label Apr 9, 2021

openjdk bot closed this Apr 9, 2021

openjdk bot added integrated Pull request has been integrated and removed sponsor Pull request is ready to be sponsored ready Pull request is ready to be integrated rfr Pull request is ready for review labels Apr 9, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

8264779: Fix doclint warnings in java/nio #3376

8264779: Fix doclint warnings in java/nio #3376

c-cleary commented Apr 7, 2021 •

edited by openjdk bot

Loading

bridgekeeper bot commented Apr 7, 2021

c-cleary commented Apr 7, 2021

openjdk bot commented Apr 7, 2021

openjdk bot commented Apr 7, 2021

mlbridge bot commented Apr 7, 2021 •

edited

Loading

AlanBateman commented Apr 7, 2021

openjdk bot commented Apr 7, 2021

AlanBateman Apr 7, 2021

AlanBateman Apr 7, 2021

c-cleary Apr 7, 2021 •

edited

Loading

naotoj Apr 7, 2021

c-cleary Apr 7, 2021

AlanBateman Apr 7, 2021

naotoj Apr 7, 2021

c-cleary Apr 7, 2021

openjdk bot commented Apr 8, 2021 •

edited

Loading

c-cleary commented Apr 9, 2021

openjdk bot commented Apr 9, 2021

ChrisHegarty commented Apr 9, 2021

openjdk bot commented Apr 9, 2021

8264779: Fix doclint warnings in java/nio #3376

8264779: Fix doclint warnings in java/nio #3376

Conversation

c-cleary commented Apr 7, 2021 • edited by openjdk bot Loading

Progress

Issue

Reviewers

Reviewing

bridgekeeper bot commented Apr 7, 2021

c-cleary commented Apr 7, 2021

openjdk bot commented Apr 7, 2021

openjdk bot commented Apr 7, 2021

mlbridge bot commented Apr 7, 2021 • edited Loading

Webrevs

AlanBateman commented Apr 7, 2021

openjdk bot commented Apr 7, 2021

AlanBateman Apr 7, 2021

Choose a reason for hiding this comment

AlanBateman Apr 7, 2021

Choose a reason for hiding this comment

c-cleary Apr 7, 2021 • edited Loading

Choose a reason for hiding this comment

naotoj Apr 7, 2021

Choose a reason for hiding this comment

c-cleary Apr 7, 2021

Choose a reason for hiding this comment

AlanBateman Apr 7, 2021

Choose a reason for hiding this comment

naotoj Apr 7, 2021

Choose a reason for hiding this comment

c-cleary Apr 7, 2021

Choose a reason for hiding this comment

openjdk bot commented Apr 8, 2021 • edited Loading

c-cleary commented Apr 9, 2021

openjdk bot commented Apr 9, 2021

ChrisHegarty commented Apr 9, 2021

openjdk bot commented Apr 9, 2021

c-cleary commented Apr 7, 2021 •

edited by openjdk bot

Loading

mlbridge bot commented Apr 7, 2021 •

edited

Loading

c-cleary Apr 7, 2021 •

edited

Loading

openjdk bot commented Apr 8, 2021 •

edited

Loading