RFR: 8274771: Map, FlatMap and OrElse fluent bindings for ObservableValue [v10]

[Nir Lisker]

On Fri, 18 Mar 2022 09:55:30 GMT, John Hendrikx <jhendrikx at 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