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

[John Hendrikx]

On Mon, 21 Mar 2022 09:01:01 GMT, John Hendrikx <jhendrikx at openjdk.org> wrote:

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

I've changed the wording also to `Returns an` instead of `Creates an` or `Creates a new` -- I think we don't need to guarantee a new instance is always returned, just an instance that works as described (potentially cached or re-used).  Stream and Optional word this similar.

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

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