On Fri, 18 Mar 2022 23:55:36 GMT, Michael Strauß <mstra...@openjdk.org> wrote:
>> I've changed this to use your wording as I think it does read much better.
>>
>> Perhaps also possible:
>>
>> Creates a new {@code ObservableValue} that holds the value of a nested
>> {@code ObservableValue} supplied
>> by the given mapping function.
>>
>> ?
>
> Both seem fine, I don't have any preference over one or the other.
I struggled with finding a good description here
[previously](https://github.com/openjdk/jfx/pull/675#discussion_r777801130). I
think that mstr2 gave a good approach. What we can do if we want to have "the
best of both worlds" is to write something in this form:
<Simple slightly-inaccurate summary>. More precisely, <Correct and more
convoluted description>
I would offer something like this based on your suggestions:
Creates a new {@code ObservableValue} that holds the value of a nested {@code
ObservableValue} supplied by the
given mapping function. The result is updated when either this or the nested
{@code ObservableValue} changes.
If either this or the nested value is {@code null}, the resulting value is
{@code null} (no mapping is applied if
this value is {@code null}).
More precisely, the created {@code ObservableValue} holds the value of an
{@code ObservableValue} resulting
from applying a mapping on this {@code ObservableValue}'s value.
I'm honestly not sure the "More precisely" part is even needed at his point. Up
to you.
The `@return` description can be changed accordingly with the simplified
explanation if you think it's clearer.
You can also specify a `@throws` NPE if the mapping function parameter is
`null` instead of writing "cannot be null", like mstr2 suggested in another
place if you like this pattern.
By the way, if we change "Creates an..." to "Creates a new..." we should change
it in the other methods. I don't think there's a difference.
-------------
PR: https://git.openjdk.java.net/jfx/pull/675
