Skip to content
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

8267329: Modernize Javadoc code to use instanceof with pattern matching #4105

Closed

Conversation

@igraves
Copy link
Member

@igraves igraves commented May 19, 2021


Progress

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

Issue

  • JDK-8267329: Modernize Javadoc code to use instanceof with pattern matching

Reviewers

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 4105

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

Using diff file

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

@bridgekeeper
Copy link

@bridgekeeper bridgekeeper bot commented May 19, 2021

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

Loading

@openjdk
Copy link

@openjdk openjdk bot commented May 19, 2021

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

  • javadoc

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.

Loading

@mlbridge
Copy link

@mlbridge mlbridge bot commented May 19, 2021

Loading

Copy link
Member

@pavelrappo pavelrappo left a comment

Ian, thanks for doing this carefully and for getting rid of superfluous null checks.

Opinion: prefer shorter binder names. instanceof AVeryLongTypeName aVeryLongTypeName feels verbose given the small scope of a binder. (You don't need to change anything.)

Update the copyright year.

Loading

output.append(o instanceof String str ?
str : o.toString());
Copy link
Member

@pavelrappo pavelrappo May 19, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A briefer equivalent would look like this:

output.append(o.toString);

Loading

if (instance == null || !(instance instanceof Messager))
if (!(instance instanceof Messager messenger))
throw new InternalError("no messager instance!");
return (Messager)instance;
return messenger;
Copy link
Member

@pavelrappo pavelrappo May 19, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Every project has quirks. Out of many quirks of JavaDoc, we love this one the most. Perhaps you misread that type's name: it's Messager [sic!]. Please rename the variable either to messager or to a shorter one.

Loading

Copy link
Contributor

@jonathan-gibbons jonathan-gibbons May 19, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pavelrappo let's consider changing this name sometime (not now)

Loading

Copy link
Member

@pavelrappo pavelrappo left a comment

Although I like it, let's wait for my teammates to catch up on this PR. For their convenience, here are some links to a similar effort elsewhere:

Loading

@openjdk
Copy link

@openjdk openjdk bot commented May 19, 2021

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

8267329: Modernize Javadoc code to use instanceof with pattern matching

Reviewed-by: prappo, jjg

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

  • f04db5f: 8224158: assertion related to NPE at DynamicCallSiteDesc::withArgs should be reworded
  • 838a007: 8267584: The java.security.krb5.realm system property only needs to be defined once
  • f2d880c: 8266400: importkeystore fails to a password less pkcs12 keystore
  • f5562f1: 8258535: jvm.ClassReader should set the accessor to the corresponding record component
  • d8e6e28: 8267544: (test) rmi test NonLocalSkeleton fails if network has multiple adapters with the same address
  • f453166: 8267578: Remove unnecessary preview checks
  • 49f622c: 8208747: [a11y] [macos] In Optionpane Demo, inside ComponentDialog Example, unable to navigate to all items, with VO on
  • 54520fb: 8267580: The method JavacParser#peekToken is wrong when the first parameter is not zero
  • 3113910: 8267553: Extra JavaThread assignment in ClassLoader::create_class_path_entry()
  • 4d26f22: 8264304: Create implementation for NSAccessibilityToolbar protocol peer
  • ... and 19 more: https://git.openjdk.java.net/jdk/compare/81f39ed3e0176b75dee1c8db24041545bcc68a86...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.

Loading

@openjdk openjdk bot added the ready label May 19, 2021
@igraves
Copy link
Member Author

@igraves igraves commented May 19, 2021

No problem. All good suggestions. We can wait until there are more eyes on before proceeding.

Loading

Copy link
Contributor

@jonathan-gibbons jonathan-gibbons left a comment

Thanks ... I think ... with a side of grumble.
It's bad enough people using IDE driven refactoring; it's even worse when there appears to be a manual component of trying to match (often unsuccessfully) the existing style, such as it is.
These module-wide refactorings can and will cause merge conflicts with other ongoing work in progress. In my opinion, this sort of change is better done when the code is being modified for other more legitimate reasons.

Loading

if (o == null) {
c.add("{" + m.group(1) + "}");
} else if (o instanceof String) {
c.add((String) o);
} else if (o instanceof Content) {
c.add((Content) o);
} else if (o instanceof String str) {
c.add(str);
} else if (o instanceof Content con) {
c.add(con);
}

Copy link
Contributor

@jonathan-gibbons jonathan-gibbons May 19, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess at some point this becomes "pattern switch" or whatever the feature is called ... but not yet

Loading

Copy link
Member

@pavelrappo pavelrappo May 24, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The feature you are talking about is called "Pattern Matching for switch". The feature is described as a preview feature by JEP 406, which is currently proposed to target JDK 17.

Loading

Loading
Loading
@@ -51,8 +51,7 @@ public LinkOutputImpl() {

@Override
public void append(Object o) {
output.append(o instanceof String ?
(String) o : ((LinkOutputImpl)o).toString());
output.append(o.toString());
Copy link
Contributor

@jonathan-gibbons jonathan-gibbons May 19, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There may be a change in behavior here, for "invalid" arguments, which will now use .toString() instead of throwing CCE.

Loading

Copy link
Member Author

@igraves igraves May 19, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My first reaction is in agreement, but upon further inspection it seems that this class is not used by anything in the module. Interestingly its documentation header warns not to rely on its behavior to remain the same.

Loading

Copy link
Contributor

@jonathan-gibbons jonathan-gibbons May 19, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation header is a standard langtools warnings to all those people that rely on access to javac and javadoc internals.

Class not used ... wow, correct. I'll file an RFE to investigate and remove it.

Loading

Copy link
Member

@pavelrappo pavelrappo May 20, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There may be a change in behavior here, for "invalid" arguments, which will now use .toString() instead of throwing CCE.

Jon is right about the behavior change. That was a sloppy suggestion on my part. Sorry, Ian; you should revert that to your original version. Jon has created an RFR to remove LinkOutputImpl and LinkOutput: https://git.openjdk.java.net/jdk/pull/4121

Loading

Copy link
Member

@pavelrappo pavelrappo May 20, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correction. Instead of reverting to your original version, you should change it to this:

    @Override
    public void append(Object o) {
        output.append(o instanceof String s ? s : ((LinkOutputImpl) o).toString());
    }

Loading

Loading
Loading
Loading
Loading
Loading
Loading
Copy link
Contributor

@jonathan-gibbons jonathan-gibbons left a comment

OK, a couple of suggestions, but it would be stylistically consistent to leave some names inconsistent! :-)

Loading

} else if (element instanceof ModuleElement modElem) {
basePath = DocPaths.forModule(modElem);
Copy link
Contributor

@jonathan-gibbons jonathan-gibbons May 19, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missed this last time; maybe "mdle" would be more in line with usage elsewhere

Loading

if (c instanceof TextBuilder txtBldr) {
tb = txtBldr;
} else {
contents.add(tb = new TextBuilder());
}
Copy link
Contributor

@jonathan-gibbons jonathan-gibbons May 19, 2021

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess we have competing demands for short names!

Loading

@openjdk
Copy link

@openjdk openjdk bot commented May 20, 2021

@igraves this pull request can not be integrated into master due to one or more merge conflicts. To resolve these merge conflicts and update this pull request you can run the following commands in the local repository for your personal fork:

git checkout update-javadoc-instanceof-pattern
git fetch https://git.openjdk.java.net/jdk master
git merge FETCH_HEAD
# resolve conflicts and follow the instructions given by git merge
git commit -m "Merge master"
git push

Loading

@openjdk openjdk bot added merge-conflict and removed ready labels May 20, 2021
@openjdk openjdk bot added ready and removed merge-conflict labels May 24, 2021
@igraves
Copy link
Member Author

@igraves igraves commented May 24, 2021

/integrate

Loading

@openjdk openjdk bot closed this May 24, 2021
@openjdk openjdk bot added integrated and removed ready labels May 24, 2021
@openjdk openjdk bot removed the rfr label May 24, 2021
@openjdk
Copy link

@openjdk openjdk bot commented May 24, 2021

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

  • 209769b: 8267347: CDS record_linking_constraint asserts with unregistered class
  • a5467ae: 8267423: Fix copyrights in jpackage tests
  • bb085f6: 8265362: java/net/Socket/UdpSocket.java fails with "java.net.BindException: Address already in use" (macos-aarch64)
  • 640a2af: 8267184: Add -Djava.security.manager=allow to tests calling System.setSecurityManager
  • f04db5f: 8224158: assertion related to NPE at DynamicCallSiteDesc::withArgs should be reworded
  • 838a007: 8267584: The java.security.krb5.realm system property only needs to be defined once
  • f2d880c: 8266400: importkeystore fails to a password less pkcs12 keystore
  • f5562f1: 8258535: jvm.ClassReader should set the accessor to the corresponding record component
  • d8e6e28: 8267544: (test) rmi test NonLocalSkeleton fails if network has multiple adapters with the same address
  • f453166: 8267578: Remove unnecessary preview checks
  • ... and 23 more: https://git.openjdk.java.net/jdk/compare/81f39ed3e0176b75dee1c8db24041545bcc68a86...master

Your commit was automatically rebased without conflicts.

Pushed as commit ebc9357.

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

Loading

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
3 participants