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

[John Hendrikx]

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.

@nlisker @mstr2 I've done another pass, using all the suggestions, and also by looking closely at how things are worded in the documentation for Optional and Stream.  This resulted in a few additional changes.  I've left out the "more precisely" parts as I think we all agree it adds little extra value.  Please have another look.

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

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