[jfx15] RFR: 8228570: Add various documentation clarifications [v5]
arapte at openjdk.java.net
Thu Aug 13 05:04:12 UTC 2020
On Wed, 12 Aug 2020 10:26:06 GMT, Nir Lisker <nlisker at openjdk.org> wrote:
>> Adds clarifications to the documentation in various places. Some notes:
>> * Point 6 should probably be deferred until it is verified that the tutorials are correct enough, seeing as they were
>> updated to Java 8 only.
>> * Point 8 has been deferred until all the animation bugs have been resolevd.
>> * Point 5: I wrote new documentation about the `extractor` for the `observableArrayList(Callback<E, Observable>
>> extractor)` method. Later I found that `observableList(List<E> list, Callback<E, Observable> extractor)` already
>> talks about it (I updated it too). I'm not sure which of them we want to keep, or maybe merge them.
>> * Point 1: I think that it's necessary to mention the internal implementation behavior even if it requires a caveat that
>> this is only the current behavior and may change in the future. What constitutes a "change" is extremely important and
>> there is no way for the user to know it. I've tripped on this hard when using ReactFX which uses object equality
>> instead, so when the JavaFX observables are wrapped by ReactFX observables, the behavior changes silently.
>> I think that in the future we will want to let the user define what a change is (for example, by creating an
>> overridable method with the current behavior as the default, or using object equality and letting the user override
>> that, although that's more risky). Even a `HashMap` that uses object equality has the sister implementation
>> `IndentityHashMap` to deal with this ambiguity.
> Nir Lisker has updated the pull request incrementally with one additional commit since the last revision:
> Addressed review comments
Marked as reviewed by arapte (Reviewer).
More information about the openjfx-dev