On Sun, 9 Jul 2023 21:20:02 GMT, John Hendrikx <jhendr...@openjdk.org> wrote:
>> modules/javafx.base/src/main/java/javafx/beans/Observable.java line 99:
>>
>>> 97: /**
>>> 98: * Creates a {@link Subscription} on this value which calls the
>>> given
>>> 99: * {@code runnable} whenever it becomes invalid.
>>
>> I think the documentation for these new methods should go into more detail
>> and clearly explain the semantics. These are fundamental concepts, and I
>> think it's a good idea to err on the side of over-explaining. Here's a
>> suggestion:
>>
>>
>> Creates a {@code Subscription} for invalidation events of this {@code
>> Observable}.
>> <p>
>> The specified {@code runnable} will be invoked when the {@code Observable}
>> transitions to the
>> <em>invalid</em> state. This happens when the observed value is changed,
>> usually by calling
>> the {@link ObservableValue#setValue} method. Note that the specified {@code
>> runnable} will not
>> be invoked for subsequent value changes unless the {@code Observable} has
>> transitioned to the
>> <em>valid</em> state again, usually by invoking the {@link
>> ObservableValue#getValue} method.
>> <p>
>> An {@code Observable} is automatically validated on every change when a
>> {@link ChangeListener}
>> or a {@link Consumer} or {@link BiConsumer} subscription is added.
>
> Sure, that's a good suggestion, I may have been overly brief to avoid
> repeating what is known for invalidation listeners, but as this method does
> not mention invalidation listeners (and only uses them internally for now) a
> full explanation would be good to add.
Another option would be to refer to the documentation for
`InvalidationListener` or `Observable.addListener(InvalidationListener)`, both
of which could be improved a bit in a separate PR.
-------------
PR Review Comment: https://git.openjdk.org/jfx/pull/1069#discussion_r1257544619
