Re: [jfx15] RFR: 8228570: Add various documentation clarifications [v5]
On Wed, 12 Aug 2020 10:26:06 GMT, Nir Lisker 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 >> extractor)` method. Later I found that `observableList(List list, >> Callback 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). - PR: https://git.openjdk.java.net/jfx/pull/276
Re: [jfx15] RFR: 8228570: Add various documentation clarifications [v5]
On Wed, 12 Aug 2020 10:26:06 GMT, Nir Lisker 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 >> extractor)` method. Later I found that `observableList(List list, >> Callback 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 kcr (Lead). - PR: https://git.openjdk.java.net/jfx/pull/276
Re: [jfx15] RFR: 8228570: Add various documentation clarifications [v5]
> 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 > extractor)` method. Later I found that `observableList(List list, > Callback 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 - Changes: - all: https://git.openjdk.java.net/jfx/pull/276/files - new: https://git.openjdk.java.net/jfx/pull/276/files/3bb17c7e..93ad171e Webrevs: - full: https://webrevs.openjdk.java.net/jfx/276/webrev.04 - incr: https://webrevs.openjdk.java.net/jfx/276/webrev.03-04 Stats: 25 lines in 2 files changed: 5 ins; 2 del; 18 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