On Mon, 10 Aug 2020 16:08:31 GMT, Nir Lisker <nlis...@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:
>
> Reverted transforms-related changes and added API note for getProperties
I left a couple inline comments. I think the changes to the two `FXCollections`
methods that take an extractor
parameter are fine, other than the one comment I made which would help unify
the docs between the two methods.
modules/javafx.base/src/main/java/javafx/collections/FXCollections.java line
324:
> 323: * a change in one of those observables, the user is notified of it
> through an
> 324: * {@link ListChangeListener.Change#wasUpdated() update} change of
> an attached {@code ListChangeListener}.
> These changes 325: * are unrelated to the changes made to the observable
> list itself using methods such as {@code
> add} and {@code remove}.
I suggest to change this to `@linkplain`.
modules/javafx.base/src/main/java/javafx/collections/FXCollections.java line
330:
> 329: * @param <E> The type of List to be wrapped
> 330: * @param extractor element to Observable[] converter. Observable
> objects are listened for changes on the
> element. 331: * @return a newly created ObservableList
You can probably drop the second sentence (and thus the period after the first)
if you copy the following from
`observableList` to the description of this method:
Observable objects returned by the extractor (applied to each list element) are
listened for changes...
modules/javafx.controls/src/main/java/javafx/scene/control/Pagination.java line
90:
> 89: * public Node call(Integer pageIndex) {
> 90: * return new Label(pageIndex + 1 + ". Lorem ipsum dolor sit
> amet,\n"
> 91: * + "consectetur adipiscing elit,\n"
Do you think we need keep the non-lambda version of the example? It's up to you.
modules/javafx.graphics/src/main/java/javafx/animation/Timeline.java line 49:
> 48: * <p>
> 49: * {@code Timeline} processes individual a {@code KeyFrame} at or after
> the specified
> 50: * time interval elapsed, it does not guarantee the exact time when a
> {@code KeyFrame}
The `a` and `KeyFrame` are switched in this sentence; it should be `processes
an individual @{KeyFrame}` instead.
Also, the previous paragraph should say either `processes individual {@code
KeyFrame}s sequentially` or `processes
individual {@code KeyFrame} objects sequentially` or similar.
-------------
PR: https://git.openjdk.java.net/jfx/pull/276
