8332103: since-checker - Add missing @ since tags to java.desktop #19192

nizarbenalla · 2024-05-11T17:52:28Z

If you're currently reviewing this PR, thank you!
Most fixes here are according to the reports by the since checker tool in #18934 and are pretty simple.

To make reviewing easier

BasicSliderUI has the constructor public BasicSliderUI(JSlider b) for a long time so the default constructor (without parameters) didn't exist until JDK 16

For the package-info files, it is pretty hard to find source code of JDK 1-5 so I used the grep command to find the oldest instance of an @since in those packages.

I found instances of @since 1.1 in the other packages but javax/swing/plaf/synth/package-info.java might be worth checking as most classes there had no @since.

Progress

Change must be properly reviewed (1 review required, with at least 1 Reviewer)
Change must not contain extraneous whitespace
Commit message must refer to an issue

Issue

JDK-8332103: since-checker - Add missing @ since tags to java.desktop (Sub-task - P4)

Reviewers

Tejesh R (@TejeshR13 - Reviewer) ⚠️ Review applies to dec1c1b5
Alexey Ivanov (@aivanov-jdk - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/19192/head:pull/19192
$ git checkout pull/19192

Update a local copy of the PR:
$ git checkout pull/19192
$ git pull https://git.openjdk.org/jdk.git pull/19192/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 19192

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

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/19192.diff

Webrev

Link to Webrev Comment

bridgekeeper · 2024-05-11T17:52:58Z

👋 Welcome back nizarbenalla! 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 · 2024-05-11T17:53:28Z

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

8332103: since-checker - Add missing @ since tags to java.desktop

Reviewed-by: tr, aivanov

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

f23295e: 8334600: TEST java/net/MulticastSocket/IPMulticastIF.java fails on linux-aarch64
741a0f3: 8334241: Adjust API docs side bar dimensions

Please see this link for an up-to-date comparison between the source branch of this pull request and the master 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.

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 (@TejeshR13, @aivanov-jdk) 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).

openjdk · 2024-05-11T17:53:48Z

@nizarbenalla The following label will be automatically applied to this pull request:

client

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 · 2024-05-12T18:56:37Z

Webrevs

TejeshR13

I did verify the updates against the release versions and looks good to me.

prrace · 2024-05-14T21:53:24Z

src/java.desktop/share/classes/javax/swing/package-info.java

@@ -149,5 +149,7 @@
 * </ul>
 *
 * @serial exclude
+ *
+ * @since 1.1


This isn't right. Where did you get this from ?
Swing only became part of the JDK in JDK 1.2
It was an unbundled library before then.
If you find any @SInCE 1.1 tags in the Swing API they are a mistake.

My bad then, this is a mistake.

src/java.desktop/share/classes/javax/swing/plaf/basic/BasicSliderUI.java

prrace · 2024-05-14T21:59:35Z

I'm not sure I understand the methodology here.
I think there must be hundreds of similar missing tags and this seems to be just a few random ones that aren't always correct.

nizarbenalla · 2024-05-14T23:45:23Z

As I'm using the historical data built into javac to determine the correct @since tag to be used, I can only check code added after JDK 9.
So a lot of errors in "older" code will go unnoticed, but I can make sure new tags are correct.
When an @since is missing from an element added in newer JDK releases I get an accurate error message i.e

method: void javax.swing.JSlider.AccessibleJSlider.stateChanged(javax.swing.event.ChangeEvent): @since version is 9 instead of 16

but for older code you can only guess "Element: X existed before JDK 10". So I was left to check on my own, and made a mistake.

aivanov-jdk · 2024-05-29T11:38:02Z

but for older code you can only guess "Element: X existed before JDK 10". So I was left to check on my own, and made a mistake.

Why is it? There's history beyond 10 and 9, yet accessing it requires more effort. In addition to that, old JDK releases are available in an archive so that you can verify if a method existed in a certain release.

If all the methods need @since marker, it has to be accurate and represent the real picture rather than an estimate.

nizarbenalla · 2024-05-29T21:40:17Z

Why is it? There's history beyond 10 and 9

As I've explained before, a program relying on the historical data built into javac can only give accurate reports for newer releases. As that data only goes back so far. I was left to investigate and couldn't find source code of JDK 1-2 internally after some digging.

To fix old code, we would need to find a new way to map elements. I don't think this would need to be added to the checker tool as checking old code doesn't need to run regularly. It can be a one time script, fix it once and be done with this. It's out of scope for my current work.

The good thing is that once these tags (in this PR) are fixed, this will no longer be an issue and the errors reported will be clear and simple. As we would only be dealing with missing/wrong information in current releases.

I agree I should've looked more, because the @since values deserve to be correct. (I am not disputing that I made a mistake)

nizarbenalla · 2024-06-03T23:33:53Z

here is the report from the @since checker tool java.desktop

        SinceChecker java.desktop
STDERR:
method: void java.awt.geom.Path2D.Double.trimToSize(): `@since` version is 9 instead of 10
method: void java.awt.geom.Path2D.Float.trimToSize(): `@since` version is 9 instead of 10
Unable to retrieve `@since` for Package: package: java.beans
Unable to retrieve `@since` for Package: package: javax.swing
method: void javax.swing.DefaultListModel.addAll(java.util.Collection): `@since` version is 9 instead of 11
method: void javax.swing.DefaultListModel.addAll(int,java.util.Collection): `@since` version is 9 instead of 11
method: void javax.swing.JSlider.AccessibleJSlider.stateChanged(javax.swing.event.ChangeEvent): `@since` version is 9 instead of 16
method: int javax.swing.JSlider.AccessibleJSlider.getAccessibleActionCount(): `@since` version is 9 instead of 17
method: java.lang.String javax.swing.JSlider.AccessibleJSlider.getAccessibleActionDescription(int): `@since` version is 9 instead of 17
method: boolean javax.swing.JSlider.AccessibleJSlider.doAccessibleAction(int): `@since` version is 9 instead of 17
method: void javax.swing.DefaultComboBoxModel.addAll(java.util.Collection): `@since` version is 9 instead of 11
method: void javax.swing.DefaultComboBoxModel.addAll(int,java.util.Collection): `@since` version is 9 instead of 11
method: void javax.swing.plaf.basic.BasicSliderUI.<init>(): `@since` version is 9 instead of 16
Unable to retrieve `@since` for Package: package: javax.swing.plaf.synth
field: javax.swing.text.DefaultEditorKit:beginLineUpAction: `@since` version is 9 instead of 20
field: javax.swing.text.DefaultEditorKit:endLineDownAction: `@since` version is 9 instead of 20
java.lang.Exception: The `@since` checker found 16 problems
        at SinceChecker.checkModule(SinceChecker.java:262)
        at SinceChecker.main(SinceChecker.java:123)
        at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103)
        at java.base/java.lang.reflect.Method.invoke(Method.java:580)
        at com.sun.javatest.regtest.agent.MainActionHelper$AgentVMRunnable.run(MainActionHelper.java:333)
        at java.base/java.lang.Thread.run(Thread.java:1575)

JavaTest Message: Test threw exception: java.lang.Exception
JavaTest Message: shutting down test


TEST RESULT: Failed. Execution failed: `main' threw exception: java.lang.Exception: The `@since` checker found 16 problems

aivanov-jdk · 2024-06-04T16:17:54Z

method: void java.awt.geom.Path2D.Double.trimToSize(): @since version is 9 instead of 10
method: void java.awt.geom.Path2D.Float.trimToSize(): @since version is 9 instead of 10

In JDK 10, a new method trimToSize was added to Path2D. It is marked with @since 10.

Path2D.Float and Path2D.Double override the method or rather implement it. Does this require an explicit @since tag? I'm unsure about it.

aivanov-jdk · 2024-06-04T16:24:23Z

src/java.desktop/share/classes/java/awt/geom/Path2D.java

+        /**
+         * @since 10
+         */


Not sure it's required…

If it is, you should also add explicit {@inheritDoc}:

Suggested change

/**

* @since 10

*/

/**

* {@inheritDoc}

*

* @since 10

*/

You don't need an explicit {@inheritDoc} although you may choose to do so for explicit clarity.

@since can be omitted for a member if the value would be the same as on the enclosing class

When present, @since on a method should indicate the first release in which the method is available for use on that class, with that VM signature (includes args and return type)

Thank you for clarification, @jonathan-gibbons. So, @since is required here.

I prefer an explicit {@inheritDoc}, this way the javadoc comment doesn't look empty. I'm fine without adding {@inheritDoc} though.

aivanov-jdk · 2024-06-12T11:52:47Z

Referring to the discussion about BasicSliderUI() constructor:

Hmm, the explicit default constructor was added in JDK 16, but it was implicit before then.

I believe there was no default constructor in BasicSliderUI() because there was a constructor with a parameter BasicSliderUI(JSlider b).

Thus, this case seem to be correct BasicSliderUI() is available since 16.

It seems that BasicSliderUI() was added by the mistake? it was not mentioned in the bug report... [JDK-8250852] Seems it is too late to delete it?

I agree. It shouldn't have been added.

Instead of adding @since, the constructor should be removed. It requires a CSR.

The longer it exists, the more chances there are that it's used.

Taking all these points into account all these points above, adding @since 16 to the no-argument constructor of BasicSliderUI() is correct.

How do we remove this constructor? Can it be removed right away? Should it be deprecated for several releases before it's removed?

@prrace @prsadhuk @mrserb

aivanov-jdk · 2024-06-12T11:54:26Z

src/java.desktop/share/classes/javax/swing/plaf/synth/package-info.java

+ *
+ * @since 1.5


This is correct, I verified the javax.swing.plaf.synth package is available in Java 5 but it wasn't in Java 1.4.

mrserb · 2024-06-12T20:55:51Z

How do we remove this constructor? Can it be removed right away? Should it be deprecated for several releases before it's removed?

Just delete it in all versions of 17+?

aivanov-jdk · 2024-06-18T17:09:08Z

How do we remove this constructor? Can it be removed right away? Should it be deprecated for several releases before it's removed?

Just delete it in all versions of 17+?

Now it is part of Java 17 and 21. It can't be removed from these releases, I believe.

Can it be removed quickly from the upcoming JDK 23? Probably, not as well.

aivanov-jdk · 2024-06-20T13:13:01Z

How do we remove this constructor? Can it be removed right away? Should it be deprecated for several releases before it's removed?

Just delete it in all versions of 17+?

Now it is part of Java 17 and 21. It can't be removed from these releases, I believe.

Can it be removed quickly from the upcoming JDK 23? Probably, not as well.

I've submitted the follow-up bugs to deal with the no-arg constructor BasicSliderUI():

JDK-8334580: Deprecate no-arg constructor BasicSliderUI() for removal
JDK-8334581: Remove no-arg constructor BasicSliderUI()

The plan is to deprecate BasicSliderUI() for removal in 23 and then to remove it in 25 or, if possible, in 24.

aivanov-jdk

I verified all the added @since declarations, I found no inconsistencies.

The no-arg constructor BasicSliderUI() was added in 16, therefore @since 16 is correct. The constructor will be deprecated and removed by the follow-up bugs.

nizarbenalla · 2024-06-24T13:55:59Z

Thank you Alexey and Tejesh for your reviews!

/integrate

openjdk · 2024-06-24T13:56:25Z

@nizarbenalla
Your change (at version 7e8244d) is now ready to be sponsored by a Committer.

aivanov-jdk

The PR still looks good for me.

Yet I suggest waiting until #19819 is integrated. It will facilitate reviewing the CSR and backporting that change to jdk23.

Once PR 19819 is integrated, you'll have to merge master into your PR branch and resolve the conflict.

Thank you for your understanding.

nizarbenalla · 2024-06-24T19:32:15Z

Let me add a new commit to remove the sponsor label

aivanov-jdk · 2024-06-24T20:38:47Z

Let me add a new commit to remove the sponsor label

Thank you!

# Conflicts: # src/java.desktop/share/classes/javax/swing/plaf/basic/BasicSliderUI.java

aivanov-jdk

Looks good to me.

Thank you for waiting and then resolving the conflict.

nizarbenalla · 2024-06-26T10:25:49Z

Thank you Aleksei!

/Integrate

nizarbenalla · 2024-06-26T11:17:23Z

/integrate

openjdk · 2024-06-26T11:18:10Z

@nizarbenalla
Your change (at version 5e4e908) is now ready to be sponsored by a Committer.

aivanov-jdk · 2024-06-26T14:38:53Z

/sponsor

openjdk · 2024-06-26T14:39:22Z

Going to push as commit 8591eff.
Since your change was applied there have been 6 commits pushed to the master branch:

8374d16: 8335006: C2 SuperWord: add JMH benchmark VectorLoadToStoreForwarding.java
4ffc5e6: 8326705: Test CertMsgCheck.java fails to find alert certificate_required
efb905e: 8334618: ubsan: support setting additional ubsan check options
b2ac725: 8327380: Add tests for Shenandoah barrier expansion optimization
f23295e: 8334600: TEST java/net/MulticastSocket/IPMulticastIF.java fails on linux-aarch64
741a0f3: 8334241: Adjust API docs side bar dimensions

Your commit was automatically rebased without conflicts.

openjdk · 2024-06-26T14:39:29Z

@aivanov-jdk @nizarbenalla Pushed as commit 8591eff.

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

Add @since tags to java.desktop

dec1c1b

openjdk bot added the client [email protected] label May 11, 2024

nizarbenalla marked this pull request as ready for review May 12, 2024 18:53

openjdk bot added the rfr Pull request is ready for review label May 12, 2024

TejeshR13 approved these changes May 14, 2024

View reviewed changes

prrace reviewed May 14, 2024

View reviewed changes

src/java.desktop/share/classes/javax/swing/plaf/basic/BasicSliderUI.java Show resolved Hide resolved

Swing was added in JDK 1.2

7e8244d

nizarbenalla changed the title ~~8332103: Add missing @since tags to java.desktop~~ 8332103: since-checker - Add missing @since tags to java.desktop Jun 3, 2024

nizarbenalla changed the title ~~8332103: since-checker - Add missing @since tags to java.desktop~~ 8332103: since-checker - Add missing @ since` tags to java.desktop Jun 4, 2024

nizarbenalla changed the title ~~8332103: since-checker - Add missing @ since` tags to java.desktop~~ 8332103: since-checker - Add missing @ since tags to java.desktop Jun 4, 2024

aivanov-jdk reviewed Jun 4, 2024

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Jun 11, 2024

aivanov-jdk reviewed Jun 12, 2024

View reviewed changes

aivanov-jdk approved these changes Jun 20, 2024

View reviewed changes

openjdk bot added the sponsor Pull request is ready to be sponsored label Jun 24, 2024

aivanov-jdk suggested changes Jun 24, 2024

View reviewed changes

See if an empty commit removes sponsor label

5f68fe9

openjdk bot removed the sponsor Pull request is ready to be sponsored label Jun 24, 2024

Merge remote-tracking branch 'upstream/master' into JDK-8332103

5e4e908

# Conflicts: # src/java.desktop/share/classes/javax/swing/plaf/basic/BasicSliderUI.java

aivanov-jdk approved these changes Jun 26, 2024

View reviewed changes

openjdk bot added the sponsor Pull request is ready to be sponsored label Jun 26, 2024

openjdk bot added the integrated Pull request has been integrated label Jun 26, 2024

openjdk bot closed this Jun 26, 2024

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review sponsor Pull request is ready to be sponsored labels Jun 26, 2024

nizarbenalla deleted the JDK-8332103 branch September 19, 2024 00:28

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

8332103: since-checker - Add missing @ since tags to java.desktop #19192

8332103: since-checker - Add missing @ since tags to java.desktop #19192

nizarbenalla commented May 11, 2024 •

edited by openjdk bot

Loading

bridgekeeper bot commented May 11, 2024

openjdk bot commented May 11, 2024 •

edited

Loading

openjdk bot commented May 11, 2024

mlbridge bot commented May 12, 2024 •

edited

Loading

TejeshR13 left a comment

prrace May 14, 2024

nizarbenalla May 14, 2024

prrace commented May 14, 2024

nizarbenalla commented May 14, 2024 •

edited

Loading

aivanov-jdk commented May 29, 2024

nizarbenalla commented May 29, 2024 •

edited

Loading

nizarbenalla commented Jun 3, 2024 •

edited

Loading

aivanov-jdk commented Jun 4, 2024

aivanov-jdk Jun 4, 2024

jonathan-gibbons Jun 11, 2024

aivanov-jdk Jun 12, 2024

aivanov-jdk commented Jun 12, 2024

aivanov-jdk Jun 12, 2024

mrserb commented Jun 12, 2024

aivanov-jdk commented Jun 18, 2024

aivanov-jdk commented Jun 20, 2024

aivanov-jdk left a comment

nizarbenalla commented Jun 24, 2024

openjdk bot commented Jun 24, 2024

aivanov-jdk left a comment

nizarbenalla commented Jun 24, 2024

aivanov-jdk commented Jun 24, 2024

aivanov-jdk left a comment

nizarbenalla commented Jun 26, 2024

nizarbenalla commented Jun 26, 2024

openjdk bot commented Jun 26, 2024

aivanov-jdk commented Jun 26, 2024

openjdk bot commented Jun 26, 2024

openjdk bot commented Jun 26, 2024

8332103: since-checker - Add missing @ since tags to java.desktop #19192

8332103: since-checker - Add missing @ since tags to java.desktop #19192

Conversation

nizarbenalla commented May 11, 2024 • edited by openjdk bot Loading

Progress

Issue

Reviewers

Reviewing

Webrev

bridgekeeper bot commented May 11, 2024

openjdk bot commented May 11, 2024 • edited Loading

openjdk bot commented May 11, 2024

mlbridge bot commented May 12, 2024 • edited Loading

Webrevs

TejeshR13 left a comment

Choose a reason for hiding this comment

prrace May 14, 2024

Choose a reason for hiding this comment

nizarbenalla May 14, 2024

Choose a reason for hiding this comment

prrace commented May 14, 2024

nizarbenalla commented May 14, 2024 • edited Loading

aivanov-jdk commented May 29, 2024

nizarbenalla commented May 29, 2024 • edited Loading

nizarbenalla commented Jun 3, 2024 • edited Loading

aivanov-jdk commented Jun 4, 2024

aivanov-jdk Jun 4, 2024

Choose a reason for hiding this comment

jonathan-gibbons Jun 11, 2024

Choose a reason for hiding this comment

aivanov-jdk Jun 12, 2024

Choose a reason for hiding this comment

aivanov-jdk commented Jun 12, 2024

aivanov-jdk Jun 12, 2024

Choose a reason for hiding this comment

mrserb commented Jun 12, 2024

aivanov-jdk commented Jun 18, 2024

aivanov-jdk commented Jun 20, 2024

aivanov-jdk left a comment

Choose a reason for hiding this comment

nizarbenalla commented Jun 24, 2024

openjdk bot commented Jun 24, 2024

aivanov-jdk left a comment

Choose a reason for hiding this comment

nizarbenalla commented Jun 24, 2024

aivanov-jdk commented Jun 24, 2024

aivanov-jdk left a comment

Choose a reason for hiding this comment

nizarbenalla commented Jun 26, 2024

nizarbenalla commented Jun 26, 2024

openjdk bot commented Jun 26, 2024

aivanov-jdk commented Jun 26, 2024

openjdk bot commented Jun 26, 2024

openjdk bot commented Jun 26, 2024

nizarbenalla commented May 11, 2024 •

edited by openjdk bot

Loading

openjdk bot commented May 11, 2024 •

edited

Loading

mlbridge bot commented May 12, 2024 •

edited

Loading

nizarbenalla commented May 14, 2024 •

edited

Loading

nizarbenalla commented May 29, 2024 •

edited

Loading

nizarbenalla commented Jun 3, 2024 •

edited

Loading