On Fri, 18 Mar 2022 09:55:30 GMT, John Hendrikx <jhendr...@openjdk.org> wrote:
>> modules/javafx.base/src/main/java/javafx/beans/value/ObservableValue.java
>> line 146:
>>
>>> 144: * Creates an {@code ObservableValue} that holds the result of
>>> applying a
>>> 145: * mapping on this {@code ObservableValue}'s value. The result is
>>> updated
>>> 146: * when this {@code ObservableValue}'s value changes. If this
>>> value is
>>
>> I think a lot of the new documentation in this class sacrifices
>> understandability for precision in trying to deal with the difference
>> between "this ObservableValue" and "this ObservableValue's value".
>>
>> However, my feeling is that that's not helping users who are trying to
>> understand the purpose of the new APIs.
>> What do you think about a simplified version like this:
>> `Creates a new {@ObservableValue} that applies a mapping function to this
>> {@code ObservableValue}. The result is updated when this {@code
>> ObservableValue} changes.`
>>
>> Sure, it's not literally mapping _this ObservableValue instance_, but would
>> this language really confuse readers more that the precise language?
>>
>> Another option might be to combine both:
>> `Creates a new {@ObservableValue} that applies a mapping function to this
>> {@code ObservableValue}. More precisely, it creates a new {@code
>> ObservableValue} that holds the result of applying a mapping function to the
>> value of this {@code ObservableValue}.`
>
> Yeah, agreed, it is a bit annoying to have to deal with the fact that these
> classes are wrappers around an actual value and having to refer to them as
> such to be "precise". I'm willing to make another pass at all of these to
> change the wording. What do you think @nlisker ?
I read this comment after what I wrote about `flatMap`, so mstr2 also had the
idea of "More precisely", which is good :)
I would suggested something similar to what I did there:
Creates a new {@code ObservableValue} that holds the value supplied by the
given mapping function. The result
is updated when this {@code ObservableValue} changes.
If this value is {@code null}...
More precisely, the created {@code ObservableValue} holds the result of
applying a mapping on this
{@code ObservableValue}'s value.
Same comments about `@return` and `@throws` NPE as I had for `flatMap`.
`orElse` will also becomes something like
Creates a new {@code ObservableValue} that holds this value, or the given value
if it is {@code null}. The
result is updated when this {@code ObservableValue} changes.
More precisely, the created {@code ObservableValue} holds this {@code
ObservableValue}'s value, or
the given value if it is {@code null}.
Also not sure if the "More precisely" description is needed here.
-------------
PR: https://git.openjdk.java.net/jfx/pull/675
