8251123: doclint warnings about missing javadoc tags and comments #369

mrserb · 2020-09-25T21:45:39Z

We have a number of missing javadoc tags and comments in the desktop module.
Most of the missing comments are related to the serialized form.

The fix:

Adds missing comments to the non-static/non-transient fields(even private) of the "serializable" classes
Adds comments to the "serializable" classes even if those classes are non-public
Fixes references/adds missing tags to the special methods(like readObject/writeObject)
Delete the java.awt.PeerFixer class.

I need advice about what exact change should be reviewed in the CSR(except PeerFixer removal)

Note that in some cases I added the comments to the "implementation details", so I did not specify it fully.

The old review request:
https://mail.openjdk.java.net/pipermail/beans-dev/2020-August/000423.html

Progress

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

Issue

JDK-8251123: doclint warnings about missing javadoc tags and comments

Reviewers

Jayathirth D V (@jayathirthrao - Reviewer) ⚠️ Review applies to cfc1df5
Phil Race (@prrace - Reviewer)

Download

$ git fetch https://git.openjdk.java.net/jdk pull/369/head:pull/369
$ git checkout pull/369

bridgekeeper · 2020-09-25T21:46:53Z

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

openjdk · 2020-09-25T21:48:23Z

@mrserb The following labels will be automatically applied to this pull request: 2d awt beans i18n swing.

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 (add|remove) "label" command.

mrserb · 2020-09-25T21:55:57Z

/csr

openjdk · 2020-09-25T21:56:31Z

@mrserb this pull request will not be integrated until the CSR request JDK-8252544 for issue JDK-8251123 has been approved.

mlbridge · 2020-09-25T22:00:42Z

Webrevs

01: Full - Incremental (c1d8369)
00: Full (cfc1df5)

jayathirthrao · 2020-09-28T06:30:31Z

Inputs from https://mail.openjdk.java.net/pipermail/beans-dev/2020-August/000424.html are incorporated or is this fresh git review?

mrserb · 2020-09-28T07:49:54Z

Inputs from https://mail.openjdk.java.net/pipermail/beans-dev/2020-August/000424.html are incorporated or is this fresh git review?

It is a fresh update, it changes from the old review request. I made it less "dangerous".

jayathirthrao · 2020-09-30T06:11:51Z

src/java.desktop/share/classes/java/awt/Window.java

+    /**
+     * Focus transfers for the lightweight components request should be made
+     * synchronously.
+     */


More simpler way "Focus transfers should be synchronous for lightweight component requests"

prrace · 2020-10-02T18:21:44Z

src/java.desktop/share/classes/javax/imageio/metadata/IIOMetadataNode.java

-
+/**
+ * A {@code IIODOMException} is thrown by the {@code IIOMetadataNode} in
+ * "exceptional" circumstances.


"A" -> "An"

prrace · 2020-10-02T18:31:45Z

src/java.desktop/share/classes/java/awt/ScrollPane.java

@@ -810,52 +827,3 @@ public AccessibleRole getAccessibleRole() {
    } // class AccessibleAWTScrollPane

 }
-
-/*
- * In JDK 1.1.1, the pkg private class java.awt.PeerFixer was moved to


As I mentioned in the OLD review thread for hg, this definitely needs a CSR
and it needs to be called out.
I think it should be separated out from this fix which is about fixing doclint warnings but here you are making an incompatible change. Let's not mix the two.

prrace · 2020-10-02T18:33:12Z

src/java.desktop/share/classes/java/awt/CheckboxMenuItem.java

-    /*
-     * Serial Data Version
+    /**
+     * Serialized data version.
     * @serial
     */
    private int checkboxMenuItemSerializedDataVersion = 1;


OK. Good this was being discussed in the old review and it should stay.

prrace · 2020-10-02T18:34:16Z

src/java.desktop/share/classes/java/awt/ContainerOrderFocusTraversalPolicy.java

+
+    /**
+     * This constant is used when the backward focus traversal order is active.
+     */
    private final int BACKWARD_TRAVERSAL = 1;


I see you also reverted the change of these two to static so that is also good.

prrace

I think the main thing here is I would separate out removing the duplicate PeerFixer into a new bug.

I also see that the CSR is still just a pure template.

prrace · 2020-10-02T19:46:10Z

I need advice about what exact change should be reviewed in the CSR(except PeerFixer removal)

Probably almost all of it.

mrserb · 2020-10-03T03:57:21Z

The PeerFixer is extracted to the separate CR:
https://bugs.openjdk.java.net/browse/JDK-8253965
#493

Other review comments fixed as well, CSR is in progress.

mrserb · 2020-10-03T04:45:03Z

CSR is updated.

openjdk · 2020-10-06T03:33:59Z

@mrserb 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 more details.

After integration, the commit message for the final commit will be:

8251123: doclint warnings about missing javadoc tags and comments

Reviewed-by: jdv, prr

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

5d84e95: 8204256: improve jlink error message to report unsupported class file format
4fe68f5: 8253426: jpackage is unable to generate working EXE for add-launcher configurations
c9d0407: 8253794: TestAbortVMOnSafepointTimeout never timeouts
f2f77f7: 8253761: Wrong URI syntax printed by jar --describe-module
b29e108: 8253944: Certain method references to VarHandle methods should fail
88d75c9: 8156071: List.of: reduce array copying during creation
ea27a54: 8224509: Incorrect alignment in CDS related allocation code on 32-bit platforms
4d29116: 8253433: Remove -XX:+Debugging product option
81dae70: 8253948: Memory leak in ImageFileReader
65cab55: 8253971: ZGC: Flush mark stacks after processing concurrent roots
... and 125 more: https://git.openjdk.java.net/jdk/compare/cfa3f7493149170f2b23a516bc95110dab43fd06...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.

mrserb · 2020-10-06T10:49:12Z

/integrate

openjdk · 2020-10-06T10:50:12Z

@mrserb Since your change was applied there have been 139 commits pushed to the master branch:

c9d1dcc: 8253902: G1: Starting a new marking cycle before the conc mark thread fully completed causes assertion failure
9199783: 8253565: PPC64: Fix duplicate if condition in vm_version_ppc.cpp
1728547: 8254010: GrowableArrayView::print fails to compile
6e61861: 8254046: Remove double semicolon introduced by JDK-8235521
5d84e95: 8204256: improve jlink error message to report unsupported class file format
4fe68f5: 8253426: jpackage is unable to generate working EXE for add-launcher configurations
c9d0407: 8253794: TestAbortVMOnSafepointTimeout never timeouts
f2f77f7: 8253761: Wrong URI syntax printed by jar --describe-module
b29e108: 8253944: Certain method references to VarHandle methods should fail
88d75c9: 8156071: List.of: reduce array copying during creation
... and 129 more: https://git.openjdk.java.net/jdk/compare/cfa3f7493149170f2b23a516bc95110dab43fd06...master

Your commit was automatically rebased without conflicts.

Pushed as commit f397b60.

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

8251123: doclint warnings about missing javadoc tags and comments

cfc1df5

openjdk bot added swing client-libs-dev@openjdk.org 2d client-libs-dev@openjdk.org beans client-libs-dev@openjdk.org i18n i18n-dev@openjdk.org awt client-libs-dev@openjdk.org labels Sep 25, 2020

openjdk bot added the csr Pull request needs approved CSR before integration label Sep 25, 2020

mrserb marked this pull request as ready for review September 25, 2020 21:57

openjdk bot added the rfr Pull request is ready for review label Sep 25, 2020

jayathirthrao reviewed Sep 30, 2020

View reviewed changes

jayathirthrao approved these changes Sep 30, 2020

View reviewed changes

prrace reviewed Oct 2, 2020

View reviewed changes

prrace suggested changes Oct 2, 2020

View reviewed changes

mrserb added 2 commits October 2, 2020 17:20

Update based on the feedback

e8c2a4f

Update ScrollPane.java

c1d8369

prrace approved these changes Oct 3, 2020

View reviewed changes

openjdk bot removed the csr Pull request needs approved CSR before integration label Oct 6, 2020

openjdk bot added the ready Pull request is ready to be integrated label Oct 6, 2020

openjdk bot closed this Oct 6, 2020

openjdk bot added integrated Pull request has been integrated and removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Oct 6, 2020

mrserb deleted the JDK-8251123 branch October 6, 2020 10:50

8251123: doclint warnings about missing javadoc tags and comments #369

8251123: doclint warnings about missing javadoc tags and comments #369

mrserb commented Sep 25, 2020 •

edited by openjdk bot

bridgekeeper bot commented Sep 25, 2020

openjdk bot commented Sep 25, 2020

mrserb commented Sep 25, 2020

openjdk bot commented Sep 25, 2020

mlbridge bot commented Sep 25, 2020 •

edited

jayathirthrao commented Sep 28, 2020

mrserb commented Sep 28, 2020

jayathirthrao Sep 30, 2020

prrace Oct 2, 2020

prrace Oct 2, 2020

prrace Oct 2, 2020

prrace Oct 2, 2020

prrace left a comment

prrace commented Oct 2, 2020

mrserb commented Oct 3, 2020

mrserb commented Oct 3, 2020

openjdk bot commented Oct 6, 2020

mrserb commented Oct 6, 2020

openjdk bot commented Oct 6, 2020

8251123: doclint warnings about missing javadoc tags and comments #369

8251123: doclint warnings about missing javadoc tags and comments #369

Conversation

mrserb commented Sep 25, 2020 • edited by openjdk bot

Progress

Issue

Reviewers

Download

bridgekeeper bot commented Sep 25, 2020

openjdk bot commented Sep 25, 2020

mrserb commented Sep 25, 2020

openjdk bot commented Sep 25, 2020

mlbridge bot commented Sep 25, 2020 • edited

Webrevs

jayathirthrao commented Sep 28, 2020

mrserb commented Sep 28, 2020

jayathirthrao Sep 30, 2020

Choose a reason for hiding this comment

prrace Oct 2, 2020

Choose a reason for hiding this comment

prrace Oct 2, 2020

Choose a reason for hiding this comment

prrace Oct 2, 2020

Choose a reason for hiding this comment

prrace Oct 2, 2020

Choose a reason for hiding this comment

prrace left a comment

Choose a reason for hiding this comment

prrace commented Oct 2, 2020

mrserb commented Oct 3, 2020

mrserb commented Oct 3, 2020

openjdk bot commented Oct 6, 2020

mrserb commented Oct 6, 2020

openjdk bot commented Oct 6, 2020

mrserb commented Sep 25, 2020 •

edited by openjdk bot

mlbridge bot commented Sep 25, 2020 •

edited