On Sun, 20 Mar 2022 03:28:01 GMT, Nir Lisker <nlis...@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
