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

[Nir Lisker]

On Fri, 18 Mar 2022 23:55:36 GMT, Michael Strauß <mstrauss at openjdk.org> wrote:

>> I've changed this to use your wording as I think it does read much better.
>> 
>> Perhaps also possible:
>> 
>>       Creates a new {@code ObservableValue} that holds the value of a nested {@code ObservableValue} supplied
>>       by the given mapping function.
>> 
>> ?
>
> Both seem fine, I don't have any preference over one or the other.

I struggled with finding a good description here [previously](https://github.com/openjdk/jfx/pull/675#discussion_r777801130). I think that mstr2 gave a good approach. What we can do if we want to have "the best of both worlds" is to write something in this form:

<Simple slightly-inaccurate summary>. More precisely, <Correct and more convoluted description>


I would offer something like this based on your suggestions:


Creates a new {@code ObservableValue} that holds the value of a nested {@code ObservableValue} supplied by the
given mapping function. The result is updated when either this or the nested {@code ObservableValue} changes.
If either this or the nested value is {@code null}, the resulting value is {@code null} (no mapping is applied if
this value is {@code null}).
More precisely, the created {@code ObservableValue} holds the value of an {@code ObservableValue} resulting
from applying a mapping on this {@code ObservableValue}'s value.

I'm honestly not sure the "More precisely" part is even needed at his point. Up to you.

The `@return` description can be changed accordingly with the simplified explanation if you think it's clearer.

You can also specify a `@throws` NPE if the mapping function parameter is `null` instead of writing "cannot be null", like mstr2 suggested in another place if you like this pattern.

By the way, if we change "Creates an..." to "Creates a new..." we should change it in the other methods. I don't think there's a difference.

-------------

PR: https://git.openjdk.java.net/jfx/pull/675