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

[Nir Lisker]

On Wed, 5 Jan 2022 10:51:28 GMT, John Hendrikx <jhendrikx at openjdk.org> wrote:

>> modules/javafx.base/src/main/java/javafx/beans/value/ObservableValue.java line 152:
>> 
>>> 150:      * @return an {@link ObservableValue} which provides a mapping of the value
>>> 151:      *     held by this {@code ObservableValue}, and provides {@code null} when
>>> 152:      *     this {@code ObservableValue} holds {@code null}, never null
>> 
>> No need for `@link`.
>> 
>> Since we already explained how the mapping works, maybe we can be more brief here:
>> 
>> an {@code ObservableValue} that holds the result of the mapping of the value
>> held by this {@code ObservableValue}; never {@code null} itself
>
> I think that `@return` should mention that the returned observable can hold `null`, how about: 
> 
>     an {@code ObservableValue} that holds a mapping of this {@code ObservableValue}'s value
>     or holds {@code null} when the value is {@code null}; never returns {@code null}

Good idea to mention that it can hold `null`.
I slightly prefer to say that the returned `ObservableValue` holds the result of the mapping rather than holds the mapping. I don't really mind it, but it's the phrasing used in the method description "holds the result of applying a mapping". "The mapping" itself could be mistaken for the mapping `Function` in my opinion. If you think it's clear, you can change it to that phrasing, it's also fine.

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

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