On Mon, 21 Mar 2022 09:01:01 GMT, John Hendrikx <jhendr...@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
