[jfx15] RFR: 8228570: Add various documentation clarifications

Nir Lisker nlisker at openjdk.java.net
Mon Jul 27 20:49:16 UTC 2020

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.


Commit messages:
 - Initial commit of 8228570

Changes: https://git.openjdk.java.net/jfx/pull/276/files
 Webrev: https://webrevs.openjdk.java.net/jfx/276/webrev.00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8228570
  Stats: 122 lines in 9 files changed: 60 ins; 13 del; 49 mod
  Patch: https://git.openjdk.java.net/jfx/pull/276.diff
  Fetch: git fetch https://git.openjdk.java.net/jfx pull/276/head:pull/276

PR: https://git.openjdk.java.net/jfx/pull/276

More information about the openjfx-dev mailing list