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

[Michael Strauß]

On Sun, 20 Mar 2022 03:28:01 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> 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.

I think I've arrived at the conclusing that the "more precisely" description is basically rehashing the semantics of `ObservableValue` over and over again.
It should be clear for a reader who is familiar with ObservableValue that we're not suggesting that somehow the given ObservableValue _instance_ is stored in the new ObservableValue.

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

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