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

JDK-6229853: BasicTextAreaUI:create incompletely documents the possible returned View types #10376

Closed
wants to merge 5 commits into from

Conversation

prsadhuk
Copy link
Contributor

@prsadhuk prsadhuk commented Sep 21, 2022

API specification says about BasicTextAreaUI.create "Returns a WrappedPlainView or PlainView".
But for bidi text, this method returns BoxView and other views , so the documentation needs to be updated.


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
  • Change requires a CSR request to be approved

Issues

  • JDK-6229853: BasicTextAreaUI:create incompletely documents the possible returned View types
  • JDK-8294114: BasicTextAreaUI:create incompletely documents the possible returned View types (CSR)

Reviewers

Reviewing

Using git

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

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

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 10376

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

Using diff file

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

@bridgekeeper
Copy link

bridgekeeper bot commented Sep 21, 2022

👋 Welcome back psadhukhan! 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 openjdk bot added the rfr Pull request is ready for review label Sep 21, 2022
@openjdk
Copy link

openjdk bot commented Sep 21, 2022

@prsadhuk 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.

@openjdk openjdk bot added the client client-libs-dev@openjdk.org label Sep 21, 2022
@mlbridge
Copy link

mlbridge bot commented Sep 21, 2022

Webrevs

@openjdk openjdk bot added the csr Pull request needs approved CSR before integration label Sep 21, 2022
@prsadhuk prsadhuk changed the title JDK-6229853: BasicTextAreaUI:create method are contrary to the documentation JDK-6229853: BasicTextAreaUI:create incompletely documents the possible returned View types Sep 26, 2022
Comment on lines 141 to 142
* PlainView if non-bidi text is handled
* else returns PlainParagraph or BoxView if bidi text is being handled.
Copy link
Member

Choose a reason for hiding this comment

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

You cannot specify that this method returns PlainParagraph, it's a private class. I think we should relax the specification to allow other types to be returned without mentioning the exact types.

This issue is also relevant to BasicTextFieldUI, yet it does not state explicitly what types are valid, it only gives a hint that a FieldView is returned:

Creates a view (FieldView) based on an element.

So, I propose the following text: “Creates a view for an element. Usually returns a WrappedPlainView or PlainView.”

The @return tag may be changed to “a view (for the the element)” for this class as well as for BasicTextFieldUI.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I guess we can mention "Creates a view for an element." only.
Usually returns a WrappedPlainView.. can give problem to TCK team to create testcase for all scenario. Either we mention the full returns WrappedView or PlainView. or ParagraphView or BoxView

Copy link
Member

Choose a reason for hiding this comment

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

I guess we can mention "Creates a view for an element." only. Usually returns a WrappedPlainView.. can give problem to TCK team to create testcase for all scenario.

Then the current code shouldn't have passed the TCK as the spec requires either WrappedView or PlainView.

Either we mention the full returns WrappedView or PlainView. or ParagraphView or BoxView

We can't specify it returns a package-private class.

@prrace
Copy link
Contributor

prrace commented Sep 27, 2022

Yeah I don't like the way this is documented at all. And it seems this can be swapped out on the fly when content changes too.
I think we need to start with WHY we need to document the return types. And if we don't then we don't.
If we do I'd like some detailed reasoning and contemplation of what we say about if it changes later.

@aivanov-jdk
Copy link
Member

Yeah I don't like the way this is documented at all. And it seems this can be swapped out on the fly when content changes too.

BasicTestUI implements ViewFactory which supplies views for text components.

The type of view returned depends on the document content, in particular whether it contains bidirectional text or not.

I think we need to start with WHY we need to document the return types. And if we don't then we don't. If we do I'd like some detailed reasoning and contemplation of what we say about if it changes later.

We don't need to. The views for regular text are in public API: FieldView that's used by BasicTextFieldUI as well as PlainView and WrappedPlainView which are used by BasicTextAreaUI. Yet the views for bidirectional text aren't public. So it looks, the spec hints at the public types of views returned for the regular text, yet it says nothing about package-private views which support bidirectional text.

BasicTextFieldUI says the view is likely FieldView in parentheses, but BasicTextAreaUI states it returns WrappedPlainView or PlainView (only), which is incorrect.

Can we leave the reference to public API classes?
Should we remove the references to types completely? If yes, BasicTextFieldUI.create should be updated as well.

Comment on lines 141 to 142
* PlainView if non-bidi text is handled
* else returns PlainParagraph or BoxView if bidi text is being handled.
Copy link
Member

Choose a reason for hiding this comment

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

I guess we can mention "Creates a view for an element." only. Usually returns a WrappedPlainView.. can give problem to TCK team to create testcase for all scenario.

Then the current code shouldn't have passed the TCK as the spec requires either WrappedView or PlainView.

Either we mention the full returns WrappedView or PlainView. or ParagraphView or BoxView

We can't specify it returns a package-private class.

Copy link
Member

@aivanov-jdk aivanov-jdk left a comment

Choose a reason for hiding this comment

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

Looks good if our decision is not to document the types of views returned.

@@ -83,10 +83,10 @@ protected String getPropertyPrefix() {
}

/**
* Creates a view (FieldView) based on an element.
* Creates a view based on an element.
Copy link
Member

Choose a reason for hiding this comment

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

Should we use the wording from BasicTextUI for consistency?

Suggested change
* Creates a view based on an element.
* Creates a view for an element.

The description in ViewFactory.create is more detailed, a short sentence as above is enough for TextUI.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Seems ok for consistency..
Have updated the PR and CSR...Can you please review CSR https://bugs.openjdk.org/browse/JDK-8294114

@openjdk openjdk bot removed the csr Pull request needs approved CSR before integration label Oct 17, 2022
@openjdk
Copy link

openjdk bot commented Oct 17, 2022

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

6229853: BasicTextAreaUI:create incompletely documents the possible returned View types

Reviewed-by: aivanov, 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 355 new commits pushed to the master branch:

  • f300ec8: 8294546: document where javac differs when invoked via launcher and ToolProvider
  • b269c51: 8295395: Linux Alpha Zero builds fail after JDK-8292591
  • ae60599: 8295023: Interpreter(AArch64): Implement -XX:+PrintBytecodeHistogram and -XX:+PrintBytecodePairHistogram options
  • 4d37ef2: 8295262: Build binutils out of source tree
  • 0919a3a: 8294186: AArch64: VectorMaskToLong failed on SVE2 machine with -XX:UseSVE=1
  • ec2981b: 8293711: Factor out size parsing functions from arguments.cpp
  • 5d273b9: 8295278: Add parallel class loading tests
  • 172006c: 8295333: G1: Remove unnecessary check in G1Policy::calculate_desired_eden_length_by_mmu
  • 7743345: 8294314: Minimize disabled warnings in hotspot
  • 552d8a2: 8295192: Use original configure command line when called from a script
  • ... and 345 more: https://git.openjdk.org/jdk/compare/4020ed53dd6e45cafa1d86432274700f0d4a67ca...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.

@openjdk openjdk bot added the ready Pull request is ready to be integrated label Oct 17, 2022
@prsadhuk
Copy link
Contributor Author

/integrate

@openjdk
Copy link

openjdk bot commented Oct 18, 2022

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

  • 358ac07: 8294254: [macOS] javax/swing/plaf/aqua/CustomComboBoxFocusTest.java failure
  • 490fcd0: 8293833: Error mixing types with -XX:+UseCMoveUnconditionally -XX:+UseVectorCmov
  • 529cc48: 8295396: RISC-V: Cleanup useless CompressibleRegions
  • 692cdab: 8295016: Make the arraycopy_epilogue signature consistent with its usage
  • 21a825e: 8288387: GetLocalXXX/SetLocalXXX spec should require suspending target thread
  • 8d751de: 8295231: Move all linking of native libraries to make
  • f300ec8: 8294546: document where javac differs when invoked via launcher and ToolProvider
  • b269c51: 8295395: Linux Alpha Zero builds fail after JDK-8292591
  • ae60599: 8295023: Interpreter(AArch64): Implement -XX:+PrintBytecodeHistogram and -XX:+PrintBytecodePairHistogram options
  • 4d37ef2: 8295262: Build binutils out of source tree
  • ... and 351 more: https://git.openjdk.org/jdk/compare/4020ed53dd6e45cafa1d86432274700f0d4a67ca...master

Your commit was automatically rebased without conflicts.

@openjdk openjdk bot added the integrated Pull request has been integrated label Oct 18, 2022
@openjdk openjdk bot closed this Oct 18, 2022
@openjdk openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Oct 18, 2022
@openjdk
Copy link

openjdk bot commented Oct 18, 2022

@prsadhuk Pushed as commit c33ca0c.

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

@prsadhuk prsadhuk deleted the JDK-6229853 branch October 18, 2022 05:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
client client-libs-dev@openjdk.org integrated Pull request has been integrated
3 participants