JDK-8211014 : Fix mistakes in FX API docs
  • Type: Bug
  • Component: javafx
  • Sub-Component: other
  • Affected Version: openjfx11
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2018-09-21
  • Updated: 2019-02-15
  • Resolved: 2019-02-15
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
Other
openjfx12Fixed
Related Reports
Blocks :  
Relates :  
Relates :  
Relates :  
Description
This bug will track simple javadoc fixes / typos for openjfx12.

1. Duplicated word in ContextMenu#show(Node,double,double)

    ...adjustments are made to bring the ContextMenu **back back** on screen

2. Animation#status: "In Animation" -> "An Animation"

3. TableColumnHeader#getClassCssMetaData "Returnst" -> "Returns"

4. GridPane#add (both overloads): "column,row" missing space

5. GridPane class docs, under "Row/Column Sizing": "child.However" missing space

6. Duration class docs: "Duration's" -> "Durations" (or better phrasing)

7. Application#launch (both overloads): "main method()". Will fix the formatting on the way (like "Platform.exit")

8. TableView#get/setColumnResizePolicy: "This is the function called"

9. Region#setPadding(Insets value): "By default padding is Insets.EMPTY"

10. ScrollPane: "If an application wants ..., they need to" -> "it needs to"

11. Deferred to JDK-8217270

12. JDK-8216507 RETRACTED

13. Some control classes like ProgressBar contains the line "Implementation of <ControlName> According to JavaFX UI Control API Specification" at the end. It should be removed.

14. ChoiceBox class doc: "It means configuration of the ChoiceBox is order independent." -> It means that the configuration..."
      Missing period after "ChoiceBox item selection is handled by SelectionModel".

15. Transition and Timeline have too many empty spaces around the code snippets.
Comments
Changeset: 5bc59c85d44c Author: nlisker Date: 2019-02-15 10:17 -0800 URL: http://hg.openjdk.java.net/openjfx/12-dev/rt/rev/5bc59c85d44c 8211014: Fix mistakes in FX API docs Reviewed-by: arapte, jvos, kcr
15-02-2019

This looks fine now. I'll push it shortly. If you think there is a bug in the Skin, then it might be good to file a follow-up bug. Thanks.
15-02-2019

http://cr.openjdk.java.net/~nlisker/8211014/webrev.01/ Changes in GridPane and ChoiceBox. I removed the "It means that" too since I don't see how the 3rd paragraph follows from the 2nd. I think there's also a bug in the skin which causes a set value that is not in the list of items to appear blank. That is, when the selected index is -1, the skin is instructed to show "", so the line "it is possible for the developer to specify the selected item to be something other than what is available in the predefined list." doesn't document existing behavior as far as I could tell.
15-02-2019

Looks good to me, too and I have no additional input (I have a slight, but not strong preference to remove the <p> as suggested by Ambarish, but it is optional). I can sponsor this change, once updated to address the feedback.
14-02-2019

1. I tried to produce code that exemplifies "it is possible for the developer to specify the selected item to be something other than what is available in the predefined list.", but couldn't, so I'm not sure what the documentation is saying here. 2. Will fix.
14-02-2019

Looks good. As for the 2 suggestions from @arapte: * I have no preference on 1. * I agree with the [column, row] notation for 2.
14-02-2019

I have two suggestions 1. ChoiceBox.java => From the description it looks like the third paragraph is kind of a conclusive statement of second paragraph. I think, In addition to the current change, the second and third paragraph can be merged into one paragraph. [ by removing the <p> tag on line# 62] 2. GridPane.java => column,row represents a position. Instead of changing it as 'column and row', It would be more suitable to use [column, row]. This is already used in the file for doc of addRow() , addColumn()...
14-02-2019

Webrev: http://cr.openjdk.java.net/~nlisker/8211014/webrev.00/
13-02-2019

Yeah I didn't see the edit in time.
16-01-2019

> I created JDK-8217271. I closed this as a dup, since I had already created JDK-8217270 (looks like we got our signals crossed).
16-01-2019

I created JDK-8217271.
16-01-2019

I checked, and this a result of the docs restructuring done in JDK 11 (see JDK-8195795). I think we should split out the issue of fixing this broken link into a separate P3 bug; since it is a broken link, Johan might want to backport it to openjfx11. I filed JDK-8217270 to track the broken link (point 11).
16-01-2019

Point 11 isn't an issue with hosting. The URL is wrong, so it is likely a bug in the javadoc comment itself, possibly as a result of the restructuring of docs into modules (my guess is that this link wasn't correctly updated).
16-01-2019

[~jvos] Since you're hosting the docs, can you recommend how to fix point 11 in the list above?
16-01-2019

Another JavaDoc patch: https://github.com/javafxports/openjdk-jfx/pull/227
04-10-2018

For reference: latest docs are in https://openjfx.io/javadoc/11/
22-09-2018

Around RDP1 of 12 seems a good plan. Thanks.
21-09-2018

Sure, I can take it. I assume it will be submitted for review around RDP1 of 12.
21-09-2018

[~nlisker] if you are interested, you can take this; otherwise I'll do it
21-09-2018